API de Integração SISBOV 2.0¶

Bem-vindo à documentação extendida de integração ao SISBOV 2¶

Esta documentação descreve a API REST disponibilizada pelo MAPA para integração de Certificadoras ao Sistema Brasileiro de Identificação e Certificação de Bovinos e Bubalinos (SISBOV 2.0).

ATENÇÃO

A documentação oficial, técnica e soberana é o SWAGGER.

Dediquem-se ao estudo/entendimento da API descrita no SWAGGER pois neste encontram-se os serviços com seus PathParams, QueryParams e BodyPayload. O padrão REST/HTTP obriga a existência dos PathParams, uso opcional dos QueryParams e, o BodyPayload está descrito na sessão Schema. Parâmetros pré-fixados em Enums também encontram-se descritos na sessão Schema do Swagger ao fim da página.

A documentação extendida da api está em constante evolução podendo haver inconsistências relativas ao SWAGGER, devendo o entendimento deste último prevalecer sobre a documentação extendida. Inconsistências devem ser relatadas para que seja revisionada.

Não será publicada uma documentação em formato de documento texto como aconteceu no legado.

Visão Geral do Sistema¶

O SISBOV 2.0 é a plataforma de rastreabilidade animal do Ministério da Agricultura, Pecuária e Abastecimento (MAPA). Por meio desta API, as certificadoras podem gerenciar:

Módulo	Descrição
🐄 Animal	Cadastro, atualização, desligamento, morte e consulta de animais
🏡 Propriedade	Gestão de fazendas e estabelecimentos rurais
👨‍🌾 Produtor	Cadastro e vínculo de produtores rurais
👤 Proprietário	Cadastro de proprietários de estabelecimentos
🚛 Movimentação	Transporte de animais entre propriedades
📄 GTA	Emissão e gestão de Guias de Trânsito Animal
📦 Lote	Agrupamento lógico de animais
🔢 Numeração	Controle de identificadores oficiais
📋 Solicitação de Numeração	Processo de solicitação de novos números
🏭 Frigorífico	Consulta de frigoríficos cadastrados
👷 Técnico	Gestão de técnicos de campo
🔍 Vistoria	Auditorias e inspeções de campo
📝 Ato de Solicitação	Processos administrativos do sistema

Base URLs¶

Ambiente	URL da API
Homologação	`https://api-cert-hom.sisbov.agro.br/integracao`
Produção	`https://api-cert.sisbov.agro.br/integracao`

Fluxo de Integração (Quick Start)¶

1. Solicitar credenciais de acesso (Access Key + Secret Key)
   └── Registrar o par de chaves na aplicação web SISBOV

2. Autenticar na API
   └── POST /integracao/auth/system
       Headers: X-ACCESS-KEY e X-SECRET-KEY
       Retorno: Bearer Token JWT

3. Utilizar o token em todas as requisições
   └── Authorization: Bearer <token>

4. Explorar os endpoints conforme necessidade

Padrão de Resposta¶

Todas as respostas utilizam formato JSON. O padrão geral é:

"Sucesso (200/201)"

{
  "id": "{{uuid-do-recurso}}"
}

"Listagem paginada"

{
  "content": [...],
  "currentPage": 0,
  "pageSize": 20
}

"Erro"

{
  "error": "Mensagem descritiva do erro"
}

Códigos HTTP¶

Código	Significado
`200`	Operação realizada com sucesso
`201`	Recurso criado com sucesso
`400`	Dados inválidos ou regra de negócio violada
`401`	Não autenticado — token ausente ou inválido
`403`	Sem permissão para acessar o recurso
`404`	Recurso não encontrado
`417`	Erro de negócio interno na execução

Recursos de Consulta (Listagens)¶

Todos os endpoints de listagem suportam:

Parâmetro	Tipo	Descrição	Exemplo
`pageSize`	integer	Registros por página (máx. 30)	`20`
`currentPage`	integer	Página atual (base 0)	`0`
`sort`	string	`campo,ASC;campo2,DESC`	`nome,ASC`
`search`	string	Busca textual geral	`fazenda`

Permissões por Perfil¶

Perfil	Acesso
certificadora	Acesso limitado aos próprios recursos vinculados à sua certificadora
admin	Acesso irrestrito a todos os recursos

Começar agora¶

→ Entender a Arquitetura
→ Configurar a Autenticação
→ Explorar o Swagger
→ Ver todos os Links dos ambientes