API de Consulta de Status

Sumário

1. Endpoint
2. Descrição
3. Headers
4. Request Body
5. Respostas esperadas
6. Observações

1. Endpoint #

POST https://hmlapi2.bancosemear.com.br/caas-api-status/v1/public/status

2. Descrição #

Este endpoint permite consultar o status atual de propostas (CCB) cadastradas, a partir de um ou mais identificadores: CPF, número de contrato, número de CCB ou ID de contrato. É possível informar múltiplos valores por campo, combinando filtros na mesma requisição.

3. Headers #

Key	Valor (apenas exemplo)	Descrição
client_id	`00000000-0000-0000-0000-000000000000`	Identificador único do cliente/aplicação consumidora da API
access_token	`00000000-0000-0000-0000-000000000000`	Token de acesso Bearer/JWT com escopo de autorização
Content-Type	application/json	Formato do corpo da requisição

4. Request Body #

{
  "cpf": ["00000000000", "00000000000"],
  "contractNumber": ["0000000000000", "0000000000000"],
  "ccbNumber": ["0000000000000", "0000000000000"],
  "contractId": ["00000000-0000-0000-0000-000000000000", "00000000-0000-0000-0000-000000000000"]
}

É obrigatório informar pelo menos um dos quatro campos, com pelo menos um valor válido. Os campos são independentes entre si e podem ser combinados.

É obrigatório informar pelo menos um dos quatro campos, com pelo menos um valor válido. Os campos são independentes entre si e podem ser combinados.

4.1. Tabela de campos

Campo	Tipo	Obrigatório*	Regras	Descrição
`cpf`	array de string	Não*	Somente números	Lista de CPFs a consultar
`contractNumber`	array de string	Não*	—	Lista de números de contrato
`ccbNumber`	array de string	Não*	—	Lista de números de CCB
`contractId`	array de string	Não*	—	Lista de IDs internos de contrato (UUID)

*Pelo menos um dos quatro campos deve ser enviado com ao menos um valor não vazio.

5. Respostas esperadas #

5.1. 201 — Sucesso

Retornado mesmo quando nenhuma proposta é encontrada. A resposta traz as propostas localizadas e, separadamente, os identificadores que não geraram resultado.

{
  "proposals": [
    {
      "currentStatus": "IN_PROGRESS",
      "currentStageName": "DataPrev (Averbação)",
      "stageComment": "Proposta reprovada ao realizar averbação na Dataprev.",
      "contractNumber": "0000000000000",
      "contractId": "00000000-0000-0000-0000-000000000000",
      "ccbNumber": "0000000000000",
      "cpf": "00000000000"
    }
  ],
  "notFoundCpfs": [],
  "notFoundContractNumbers": [],
  "notFoundContractIds": [],
  "notFoundCcbNumbers": []
}

Tabela de campos da resposta

Campo	Tipo	Descrição
`proposals`	array de objeto	Lista de propostas encontradas
`proposals[].currentStatus`	string	Status atual da proposta (ex.: `IN_PROGRESS`, `REPROVED`, `FINISHED`, `CANCELED`, `FAIL`)
`proposals[].currentStageName`	string	Nome da etapa atual do fluxo: AVERBACAO INTEGRACAO_DOCUMENTA DESEMBOLSO ENCARTEIRAMENTO CRIVO ANUENCIA PORTABILIDADE PARADA_ACAO_CORBAN
`proposals[].stageComment`	string	Comentário/observação da etapa atual
`proposals[].contractNumber`	string	Número do contrato
`proposals[].contractId`	string	ID interno do contrato
`proposals[].ccbNumber`	string	Número da CCB
`proposals[].cpf`	string	CPF do titular
`notFoundCpfs`	array de string	CPFs enviados na requisição que não retornaram nenhuma proposta
`notFoundContractNumbers`	array de string	Números de contrato não localizados
`notFoundContractIds`	array de string	IDs de contrato não localizados
`notFoundCcbNumbers`	array de string	Números de CCB não localizados

5.2. Exemplo — busca por CPF com múltiplas propostas

Request:

{
  "cpf": ["00000000000"]
}

Response (201):

{
  "proposals": [
    {
      "currentStatus": "IN_PROGRESS",
      "currentStageName": "Análise Interna (Semear)",
      "stageComment": "MCB: ELEGIVEL",
      "contractNumber": "0000000000000",
      "contractId": "00000000-0000-0000-0000-000000000000",
      "ccbNumber": "0000000000000",
      "cpf": "00000000000"
    },
    {
      "currentStatus": "FINISHED",
      "currentStageName": "Encarteiramento",
      "stageComment": "Encarteiramento realizado com sucesso.",
      "contractNumber": "0000000000000",
      "contractId": "00000000-0000-0000-0000-000000000000",
      "ccbNumber": "0000000000000",
      "cpf": "00000000000"
    }
  ],
  "notFoundCpfs": [],
  "notFoundContractNumbers": [],
  "notFoundContractIds": [],
  "notFoundCcbNumbers": []
}

5.3. Exemplo — identificador não encontrado

Request:

{
  "contractId": ["00000000-0000-0000-0000-000000000000"]
}

Response (201):

{
  "proposals": [],
  "notFoundCpfs": [],
  "notFoundContractNumbers": [],
  "notFoundContractIds": ["00000000-0000-0000-0000-000000000000"],
  "notFoundCcbNumbers": []
}

5.4. (400) — Requisição inválida

Retornado quando nenhum dos quatro campos de filtro é enviado, ou quando o header client_id está ausente.

[
  {
    "code": "40000",
    "title": "statusCommand",
    "detail": "Informe pelo menos um dos campos: cpf, contractNumber, ccbNumber ou contractId."
  }
]

5.5. 500 — Erro inesperado

{
  "code": "50000",
  "title": "Erro interno",
  "detail": "Ocorreu um erro inesperado ao processar a requisição."
}

6. Observações #

Todos os resultados são restritos ao client_id informado no header: propostas de outros clientes nunca são retornadas.
Os valores de currentStatus e currentStageName refletem o estágio atual do fluxo de originação e podem variar conforme o produto/parceiro.
Múltiplos valores podem ser combinados no mesmo request (ex.: cpf + contractId juntos); o resultado é a união das propostas que atendem a qualquer um dos filtros informados.