Pular para conteúdo

Comece aqui

Um roteiro curto para sair do zero até a primeira consulta com sucesso.

1. Tenha a sua chave

A API é autenticada por uma API Key, fornecida pelo suporte da GOB. Ela é enviada em toda requisição no cabeçalho X-Api-Key e vale tanto para a API de dados quanto para os Serviços.

Guarde a chave com segurança

Use uma variável de ambiente ou um cofre de segredos. Não a coloque em código front-end nem em repositórios.

2. Faça a primeira chamada

Peça um cliente, só para confirmar que a chave funciona:

curl -i -G "https://integracao.gob.com.br/api/v1/Account" \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  --data-urlencode 'searchParams={"maxSize":1,"select":["id","name"]}'

$sp = @{ maxSize = 1; select = @("id", "name") } | ConvertTo-Json -Compress

Invoke-RestMethod `
  -Uri ("https://integracao.gob.com.br/api/v1/Account?searchParams=" + [uri]::EscapeDataString($sp)) `
  -Headers @{ "X-Api-Key" = "SUA_CHAVE_AQUI" }

O esperado é 200 com um JSON neste formato:

{
  "total": 2,
  "list": [
    { "id": "688836cc750cfcf43", "name": "Nome do cliente" }
  ]
}

total é quantos registros existem no total; list traz a página pedida (aqui, 1 registro). A resposta pode trazer, além dos campos pedidos em select, alguns campos de controle, como createdById e modifiedAt.

No PowerShell, use curl.exe ou Invoke-RestMethod

No PowerShell, curl sozinho é um apelido de outro comando, com outra sintaxe. Nos exemplos desta documentação, a aba Windows usa curl.exe ou Invoke-RestMethod.

3. Busque um cliente pelo CNPJ

O CNPJ/CPF fica no campo sicCode, somente números:

curl -i -G "https://integracao.gob.com.br/api/v1/Account" \
  -H "X-Api-Key: SUA_CHAVE_AQUI" \
  --data-urlencode 'searchParams={"select":["id","name","sicCode"],"where":[{"type":"equals","attribute":"sicCode","value":"12345678000199"}]}'

$sp = @{
  select = @("id", "name", "sicCode")
  where  = @(@{ type = "equals"; attribute = "sicCode"; value = "12345678000199" })
} | ConvertTo-Json -Depth 5 -Compress

Invoke-RestMethod `
  -Uri ("https://integracao.gob.com.br/api/v1/Account?searchParams=" + [uri]::EscapeDataString($sp)) `
  -Headers @{ "X-Api-Key" = "SUA_CHAVE_AQUI" }

O id que voltar é o que você usa nas demais consultas e nos Serviços. Para descobrir os outros campos de uma entidade, veja Descobrindo campos.

4. Se algo der errado

Os erros mais comuns na primeira chamada:

Status Causa provável O que fazer
401 Chave ausente ou incorreta Confira o cabeçalho X-Api-Key e o valor da chave.
404 Nome de entidade inexistente Use o nome exato da lista de entidades, como Account.
400 searchParams malformado Envie um JSON válido e codificado na URL (--data-urlencode, encodeURIComponent ou EscapeDataString).

Na API de dados, o motivo do erro vem no cabeçalho X-Status-Reason — use -i no curl para vê-lo. Mais detalhes em Tratamento de erros.

5. Próximos passos