Pular para conteúdo

Visão geral

A API GOB oferece acesso somente leitura a 40 entidades de dados fiscais e contábeis. Todos os endpoints requerem autenticação via API Key no cabeçalho X-Api-Key.

A chave será fornecida pelo suporte

A chave de API deve ser enviada em todas as requisições. Sem ela, a resposta será 401 Unauthorized.

Informações de conexão

Item Valor
Host integracao.gob.com.br
Base path /
Esquema https
Consome application/json
Produz application/json
Versão da especificação Swagger 2.0 · API 1.0.0

Todas as URLs seguem o formato:

https://integracao.gob.com.br/api/v1/{entity}

Formas de consulta

A API permite buscar dados de duas formas. Recomendamos fortemente a forma usando searchParams (JSON codificado na URL) por ser mais flexível e segura.

Você envia todos os parâmetros de busca em um único parâmetro chamado searchParams, cujo valor é um JSON previamente codificado (JSON-encoded).

GET /api/v1/{entity}?searchParams={"maxSize":50,"offset":0,"orderBy":"modifiedAt","order":"desc","where":[{"type":"startsWith","attribute":"sicCode","value":"123"}],"select":["modifiedAt","name"]}

Em JavaScript:

const searchParams = {
  "maxSize": 50,
  "offset": 0,
  "select": ["modifiedAt", "name", "sicCode"],
  "orderBy": "modifiedAt",
  "order": "desc",
  "where": [ {"type": "startsWith", "attribute": "sicCode", "value": "123"} ]
}

const url = `https://integracao.gob.com.br/api/v1/${entity}?searchParams=${encodeURIComponent(JSON.stringify(searchParams))}`

Vantagens:

  • Permite filtros (where) complexos facilmente.
  • Menor risco de erro de formatação.
  • Mais fácil de manter e replicar.

Parâmetros enviados separadamente na URL:

GET /api/v1/{entity}?maxSize=50&offset=0&orderBy=modifiedAt&order=desc&whereGroup[0][type]=startsWith&whereGroup[0][attribute]=sicCode&whereGroup[0][value]=123

Desvantagens:

  • Difícil passar filtros complexos.
  • Mais sujeito a erros de digitação ou formatação.
  • Menos portátil.

Próximos passos

  • Autenticação

    Como enviar a sua API Key em cada requisição.

    Autenticação

  • Como consultar

    Parâmetros de paginação, ordenação e seleção de campos.

    Como consultar

  • Filtros e operadores

    Todos os operadores where suportados.

    Filtros

  • Entidades

    As 40 entidades disponíveis para leitura.

    Entidades