Postman do zero

Use este guia para montar uma collection simples e testar a API idCerberus em homologação. O objetivo é sair com dois requests funcionando:

POST /api/token-generate
POST /api/service-api

Token primeiro

Sem token válido, nenhum service protegido deve ser testado.

Service API depois

Troque apenas o campo service e os campos obrigatórios de cada consulta.

OCR com base64

Use PowerShell para copiar imagem em base64 e colar no body do Postman.

Diagnóstico rápido

Veja o que olhar quando vier falta de acesso, imagem ausente, {} ou ERROR.

1. Crie uma collection

Abra o Postman.
Clique em Collections.
Clique em New Collection.
Nomeie como idCerberus API.
Salve.

2. Crie um environment de HML

Clique em Environments.
Clique em New Environment.
Nomeie como idCerberus HML.
Crie a variável base_url.
No valor, coloque:

https://backoffice-hml.idcerberus.com

Crie a variável jwt_token.
Deixe o valor vazio por enquanto.
Salve o environment.
Selecione idCerberus HML no canto superior direito do Postman.

3. Crie o request de token

Dentro da collection, clique em Add request.
Nomeie como Gerar token.
Selecione o método POST.
Use a URL:

{{base_url}}/api/token-generate

Na aba Headers, adicione:

Key	Value
`Content-Type`	`application/json`

Na aba Body, escolha raw.
Selecione JSON.
Cole:

{
  "client": "{client}",
  "secret": "{secret}"
}

Clique em Send.
Copie o valor de access_token.
Cole esse valor na variável jwt_token do environment.

Se preferir, configure um script de teste no request de token para salvar o token automaticamente:

const data = pm.response.json();
pm.environment.set("jwt_token", data.access_token || data.token);

4. Crie o request de service-api

Dentro da collection, clique em Add request.
Nomeie como Executar service-api.
Selecione o método POST.
Use a URL:

{{base_url}}/api/service-api

Na aba Headers, adicione:

Key	Value
`Authorization`	`Bearer {{jwt_token}}`
`Content-Type`	`application/json`

Na aba Body, escolha raw.
Selecione JSON.
Cole um payload de teste.

Exemplo CPF:

{
  "service": "SERVICE_PERSON_DATA_ENRICHMENT",
  "cpf": "00000000000"
}

Exemplo CNPJ:

{
  "service": "SERVICE_REGISTRATION_DATA_CNPJ",
  "cnpj": "00000000000000"
}

5. Leia a resposta

Uma resposta de negócio costuma seguir este formato:

{
  "result": {},
  "status": {
    "code": 200,
    "message": "Success"
  },
  "onboardingStatus": "APPROVED",
  "externalId": "..."
}

Leia assim:

Campo	O que significa
`result`	Dados úteis retornados pelo service
`status.code`	Código técnico do processamento
`status.message`	Mensagem técnica do processamento
`onboardingStatus`	Resultado operacional do service, quando existir
`externalId`	Identificador para rastrear a chamada em suporte/logs

Não use apenas o HTTP status para decidir se deu certo. A API pode responder HTTP 200 e o body indicar REFUSED ou ERROR.

6. Exemplos prontos

Se quiser copiar um curl já montado, use:

Caso	Exemplo
Token HML	`auth.hml.curl`
CPF HML	`service-api-cpf.hml.curl`
CNPJ HML	`service-api-cnpj.hml.curl`
OCR CNH	`service-api-ocr-cnh.hml.curl`
OCR RG	`service-api-ocr-rg.hml.curl`
OCR cartão CNPJ	`service-api-ocr-cnpj-card.hml.curl`
OCR comprovante	`service-api-ocr-proof-of-address.hml.curl`
Face Index	`service-api-face-index.hml.curl`

Se quiser payload, retorno esperado e erro comum no mesmo lugar, abra Receitas prontas.

7. Testar OCR com imagem

Para OCR, o campo image1 deve receber base64 puro. Não envie prefixo data:image/jpeg;base64,.

CNH

$b64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\cnh.jpg"))
@{
  service = "SERVICE_OCR"
  documentType = "CNH"
  image1 = $b64
} | ConvertTo-Json -Compress | Set-Clipboard

RG frente e verso

$front = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\rg-frente.jpg"))
$back = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\rg-verso.jpg"))
@{
  service = "SERVICE_OCR"
  documentType = "RG"
  image1 = $front
  image2 = $back
} | ConvertTo-Json -Compress | Set-Clipboard

Cartão CNPJ

$b64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\cartao-cnpj.jpg"))
@{
  service = "SERVICE_OCR_CNPJ_CARD"
  image1 = $b64
} | ConvertTo-Json -Compress | Set-Clipboard

Comprovante de endereço

$b64 = [Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\comprovante.jpg"))
@{
  service = "SERVICE_OCR_PROOF_OF_ADDRESS"
  image1 = $b64
} | ConvertTo-Json -Compress | Set-Clipboard

Depois de rodar o comando, cole no Body > raw > JSON do Postman.

8. Troque para produção

Para criar um environment de produção, repita o processo e use:

https://backoffice.idcerberus.com

Use credenciais de produção e gere um novo token. Não reutilize token de HML em produção.

9. Se der erro

Sintoma	O que olhar primeiro	Ação
`401` ou `403`	Token vencido, ausente ou de outro ambiente	Gere novo token no mesmo ambiente da chamada
`Don't have access to the service`	Produto sem o service liberado para API	Conferir cadastro do produto antes de mexer no payload
`Imagem ... não encontrada`	Campo de imagem não chegou no body	Conferir `image1`, `image2`, `image1Url`, `image2Url` ou `key`
Retornou `{}`	Service sem dado para a massa ou imagem não lida	Testar massa/imagem válida e conferir `status.message`
Veio `ERROR`	Falha técnica no processamento	Guardar `externalId`, horário e service chamado
Campo esperado não veio	Campo não existe no documento ou não foi extraído	Validar imagem, tipo de documento e contrato do service

Para diagnóstico mais completo, veja Erros comuns de integração.

Primeiros passos

Suporte e referência

Fluxos principais

POST /api/service-api

Pessoas

Empresas

Catálogo técnico

Postman do zero

Postman do zero

Token primeiro

Service API depois

OCR com base64

Diagnóstico rápido

1. Crie uma collection

2. Crie um environment de HML

3. Crie o request de token

4. Crie o request de service-api

5. Leia a resposta

6. Exemplos prontos

7. Testar OCR com imagem

CNH

RG frente e verso

Cartão CNPJ

Comprovante de endereço

8. Troque para produção

9. Se der erro

​Postman do zero

Token primeiro

Service API depois

OCR com base64

Diagnóstico rápido

​1. Crie uma collection

​2. Crie um environment de HML

​3. Crie o request de token

​4. Crie o request de service-api

​5. Leia a resposta

​6. Exemplos prontos

​7. Testar OCR com imagem

​CNH

​RG frente e verso

​Cartão CNPJ

​Comprovante de endereço

​8. Troque para produção

​9. Se der erro

Postman do zero

1. Crie uma collection

2. Crie um environment de HML

3. Crie o request de token

4. Crie o request de service-api

5. Leia a resposta

6. Exemplos prontos

7. Testar OCR com imagem

CNH

RG frente e verso

Cartão CNPJ

Comprovante de endereço

8. Troque para produção

9. Se der erro