API Conta Salário Sicredi

📘

Solução em fase de piloto

Esta solução está em fase de piloto, credenciais e alguns fluxos são tratados diretamente com o associado, e podem mudar ao longo do processo.

O que é esta API

A API Conta Salário permite que empresas integrem seus sistemas próprios ou de terceiros (ERPs, plataformas de gestão) com o serviço de abertura de conta salário do Sicredi, tornando mais simples e eficiente o processo de inclusão de assalariados. Através de requisições REST com resposta assíncrona, você solicita a abertura de contas salário e acompanha o status de cada solicitação via Webhook ou consulta direta. Após o sucesso na solicitação, integrações assíncronas efetivam a abertura da conta.

Casos de uso principais:

• Abertura de conta salário na modalidade Saque
• Abertura de conta salário com Portabilidade (interna ou para outra instituição)
• Abertura de conta salário com Representante (titular menor de idade)
• Consulta de solicitações em andamento
• Consulta de instituições financeiras (para portabilidade)
• Consulta de conta de assalariado no convênio

Antes de começar

Por estar em piloto, as credenciais são disponibilizadas diretamente ao associado no momento da integração (Sandbox e Produção, via Portal do Desenvolvedor).

⚠️

Conexão mTLS obrigatória

Todas as chamadas exigem TLS com autenticação mútua, usando o certificado .CER e a chave APLICACAO.KEY. Certificados em DER precisam ser convertidos para PEM.

Ambientes disponíveis:

Passo a passo: sua primeira chamada

1. Obter token de acesso

A API usa OAuth2 Client Credentials sobre mTLS. Gere um token JWT com suas credenciais:

curl --location 'https://mtls-api-parceiro.sicredi.com.br/uat/thirdparty/auth/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=SEU_CLIENT_ID' \
  --data-urlencode 'client_secret=SEU_CLIENT_SECRET' \
  --data-urlencode 'scope=abertura.contasalario.solicitar'

Escopos disponíveis (use um ou ambos, separados por espaço):

• abertura.contasalario.solicitar — Criar solicitações de conta salário
• abertura.contasalario.consultar — Consultar solicitações, instituições e contas

Resposta esperada: um token JWT do tipo Bearer (access_token, token_type). Use-o no header Authorization: Bearer ... das chamadas seguintes.

2. Criar solicitação de conta salário (modalidade Saque)

Crie uma solicitação com POST /api/solicitacao. Note os headers obrigatórios TransactionId, Canal e Authorization-Callback:

curl -X POST \
  'https://mtls-api-parceiro.sicredi.com.br/uat/conta-salario/api/solicitacao' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN' \
  -H 'TransactionId: 2024112143673247324160202872' \
  -H 'Canal: SEU_CANAL' \
  -H 'Authorization-Callback: SUA_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "numCooperativa": "0101",
    "numAgencia": "01",
    "codConvenioFontePagadora": "XPTO",
    "cnpjFontePagadora": "11111111111111",
    "cadastros": [
      {
        "cpf": "11111111111",
        "email": "[email protected]",
        "telefone": "51999999999"
      }
    ],
    "configuracao": {
      "urlWebhook": "https://seu-sistema.com/webhook",
      "portaHttp": "443"
    }
  }'

⚠️

Composição do TransactionId (28 dígitos, idempotente)

AAAAMMDD (data) + código numérico do Canal (4 dígitos) + 16 dígitos aleatórios. Exemplo: 2024093011811561561651961512. O header Canal leva o nome do canal; o código numérico entra na composição do TransactionId.

Resposta esperada (202 Accepted):

{
  "idTransacao": "2024112143673247324160202872",
  "canal": "EXTERNO",
  "numCooperativa": "0101",
  "numAgencia": "01",
  "codConvenioFontePagadora": "XPTO",
  "cnpjFontePagadora": "11111111111111",
  "status": "PENDENTE",
  "resultado": "RECEBIDO",
  "critica": false,
  "dataCriacao": "2024-11-21T15:20:50.337129811",
  "cadastros": [
    { "cpf": "11111111111", "nome": "ASSALARIADO SICREDI", "situacao": "EM_PROCESSAMENTO" }
  ]
}

👍

Portabilidade e Representante

Usam o mesmo endpoint, adicionando os blocos portabilidade (com codBancoDestino, numAgDestino, numContaDestino, tpoConta) ou representante (com cpf) dentro de cada cadastro.

3. Consultar status da solicitação

Acompanhe o progresso com GET /api/solicitacao/{TransactionId} (header Canal obrigatório):

curl -X GET \
  'https://mtls-api-parceiro.sicredi.com.br/uat/conta-salario/api/solicitacao/2024112143673247324160202872' \
  -H 'Authorization: Bearer SEU_ACCESS_TOKEN' \
  -H 'Canal: SEU_CANAL'

Resposta esperada (200 OK):

{
  "idTransacao": "2024112143673247324160202872",
  "status": "FINALIZADO",
  "resultado": "CONCLUIDO",
  "critica": true,
  "cadastros": [
    {
      "cpf": "11111111111",
      "conta": "254554",
      "situacao": "CONCLUIDO",
      "criticas": [
        { "codigo": "RFB005", "descricao": "Data de nascimento divergente da Receita Federal.", "tipo": "INFORMATIVO" }
      ]
    }
  ]
}

Como ler o retorno (dois eixos):

• status (da solicitação): PENDENTE (em processamento) → FINALIZADO (processamento concluído)
• resultado: RECEBIDO, CONCLUIDO ou ERRO
• situacao (por cadastro/CPF): EM_PROCESSAMENTO, CONCLUIDO, etc.
• criticas: avisos INFORMATIVO (ex.: RFB004/005/006 — conta aberta com dado da Receita) ou BLOQUEANTE (ex.: RFB001/002, CCS005-017 — impedem a abertura)

4. Receber notificação via webhook (opcional)

Se você informou urlWebhook na solicitação, o Sicredi envia um POST quando o processamento finaliza. O header Authorization-Callback enviado na solicitação volta como header da notificação, permitindo validar a origem:

POST https://seu-sistema.com/webhook
Header: Authorization-Callback: SUA_API_KEY

{
  "idTransacao": "2024112143671054855866876664",
  "status": "FINALIZADO",
  "resultado": "CONCLUIDO"
}

⚠️

A notificação não traz o resultado completo

Ao recebê-la, chame a consulta do passo 3 (GET /api/solicitacao/{TransactionId}) para obter o detalhamento dos cadastros, contas criadas e críticas.

Próximos passos

Precisa de ajuda?

Durante o período de piloto, o suporte é feito diretamente via chat com o associado, para esclarecimentos e apoio em todo o processo de integração com a API Conta Salário.

• Documentação: developer.sicredi.com.br