A seguir está o Guia Técnico Completo de Integração de Certificadoras – API SISBOV 2, estruturado no padrão de documentação usado em integrações governamentais e processos de homologação MAPA/SDA.

O guia foi organizado como um manual técnico completo para equipes de integração.

Guia Técnico de Integração¶

API de Integração de Certificadoras – SISBOV 2¶

Versão: 1.0 Público-alvo: Equipes técnicas de certificadoras Objetivo: Implementação e homologação da integração com o SISBOV.

1. Introdução¶

O Sistema Brasileiro de Identificação Individual de Bovinos e Búfalos (SISBOV) é o sistema oficial de rastreabilidade individual de animais no Brasil.

A API de integração permite que sistemas de certificadoras:

registrem animais
consultem dados de rastreabilidade
atualizem eventos
validem propriedades e estabelecimentos

Essa integração garante:

integridade da rastreabilidade
padronização de dados
auditoria da cadeia produtiva
conformidade com exigências sanitárias internacionais.

2. Arquitetura da Integração¶

A API SISBOV segue arquitetura RESTful baseada em HTTP e JSON.

Características principais:

comunicação stateless
endpoints REST
payloads JSON
autenticação via token
transporte criptografado via HTTPS.

Arquitetura simplificada¶

Sistema da Certificadora
        |
        | HTTPS
        |
API SISBOV
        |
Serviços de Validação
        |
Base de Rastreabilidade

3. Segurança¶

Todas as chamadas devem utilizar:

HTTPS

Autenticação¶

A API utiliza token de acesso (Bearer Token).

Exemplo de header:

Authorization: Bearer {access_token}

Boas práticas¶

nunca expor token em logs
renovar token antes de expiração
armazenar credenciais em local seguro

4. Estrutura das Requisições¶

Requisições utilizam JSON.

Headers obrigatórios¶

Content-Type: application/json
Authorization: Bearer {token}

5. Métodos HTTP Utilizados¶

Método	Uso
GET	consulta de dados
POST	criação de registros
PUT	atualização
DELETE	remoção

6. Códigos HTTP¶

Código	Significado
200	sucesso
201	recurso criado
400	erro de validação
401	autenticação inválida
404	recurso inexistente
417	erro de regra de negócio
500	erro interno

7. Retorno 417¶

O código 417 indica falha em regras de negócio ou validação de rastreabilidade.

Exemplos:

Situação	Descrição
SISBOV_DUPLICADO	animal já registrado
ERAS_INVALIDO	propriedade não cadastrada
DATA_INVALIDA	data inconsistente
ANIMAL_INEXISTENTE	animal não localizado

8. Modelo de Dados¶

Principais entidades:

Entidade	Descrição
Animal	unidade de rastreabilidade
Produtor	responsável pela atividade pecuária
Propriedade	unidade rural
ERAS	estabelecimento aprovado
Evento	ocorrência na vida do animal

9. Número SISBOV¶

O Número SISBOV é o identificador individual do animal.

Características:

único
não reutilizável
utilizado para auditoria internacional.

Tipos¶

Tipo	Descrição
076	identificação padrão SISBOV
105	identificação derivada ou reidentificação

10. ERAS¶

ERAS significa:

Estabelecimento Rural Aprovado no SISBOV

Cada propriedade habilitada recebe um codigoEras.

Exemplo:

ERAS12345

Funções:

vincular animal à propriedade
garantir rastreabilidade
validar origem do animal.

11. Produtor vs Proprietário¶

Produtor¶

Responsável pela criação e manejo dos animais.

Proprietário¶

Detentor legal da propriedade.

Relação¶

um produtor pode operar várias propriedades
uma propriedade pode ter múltiplos produtores.

12. Campos Obrigatórios em Payload¶

Exemplo típico para cadastro de animal:

Campo	Obrigatório
numeroSisbov	sim
codigoEras	sim
sexoAnimal	sim
dataNascimento	sim
especie	sim

13. Exemplos de Payload¶

Payload válido¶

{
  "numeroSisbov": "076123456789012",
  "codigoEras": "ERAS12345",
  "sexoAnimal": "M",
  "dataNascimento": "2022-05-10",
  "especie": "BOVINO"
}

Resposta esperada:

201 Created

Payload inválido — campo obrigatório ausente¶

{
  "codigoEras": "ERAS12345"
}

Resposta esperada:

400 Bad Request

Payload inválido — ERAS inexistente¶

{
  "numeroSisbov": "076123456789012",
  "codigoEras": "ERAS99999"
}

Resposta esperada:

417 Expectation Failed

Payload inválido — SISBOV duplicado¶

{
  "numeroSisbov": "076123456789012",
  "codigoEras": "ERAS12345"
}

Resposta esperada:

417 Expectation Failed

14. Controle de Idempotência¶

Integrações devem evitar duplicidade de registros.

Boas práticas:

identificar transações
evitar retries descontrolados
validar existência antes de envio.

15. Monitoramento¶

Logs devem registrar:

endpoint
payload
resposta
código HTTP
timestamp.

16. Testes Obrigatórios¶

Antes da homologação devem ser realizados:

Teste	Resultado esperado
Cadastro válido	201
Campo ausente	400
ERAS inválido	417
SISBOV duplicado	417
Token inválido	401

17. Boas Práticas de Integração¶

✔ validar payload localmente ✔ tratar erros HTTP ✔ implementar retry controlado ✔ registrar logs completos ✔ proteger credenciais

18. Processo de Homologação¶

Etapas típicas:

acesso ao ambiente de homologação
execução de cenários de teste
validação técnica
auditoria da integração
liberação para produção.

19. Critérios de Aprovação¶

A certificadora será considerada homologada quando:

todos os cenários forem executados com sucesso
logs de integração forem apresentados
erros forem corretamente tratados.

20. Contato Técnico¶

Equipe responsável pela API SISBOV.

Solicitações:

suporte técnico
credenciais
homologação.