API pública do PRIMA

Integre os dados de captação de leite do PRIMA ao ERP, BI ou sistema interno do seu laticínio ou cooperativa. A API é somente leitura, responde em JSON e cobre produção em tempo real, fazendas fornecedoras, ranking de produtores, rotas de coleta, planejamento e alertas.

Base URL

https://prima.pastu.agr.br/api/v1

Formato

JSON · UTF-8 · HTTPS

Autenticação

Bearer token de integração

Primeira chamada em 10 segundos

curl -H "Authorization: Bearer prima_SEU_TOKEN" \
  https://prima.pastu.agr.br/api/v1/ping

Autenticação

Toda requisição exige um token de integração no header Authorization. O token é criado pelo administrador da conta no painel do PRIMA, em Configurações → API PRIMA — tokens de integração, e identifica a sua empresa: cada token acessa somente os dados do próprio laticínio/cooperativa.

No painel, clique em “Novo token”, dê um nome (ex.: ERP TOTVS) e escolha a validade: 1 ano, 2 anos ou 24 anos.

Copie o token exibido — ele começa com prima_ e aparece uma única vez. Guarde em um cofre de segredos.

Envie o token no header Authorization: Bearer em todas as chamadas.

Para desativar o acesso, revogue o token no painel — o efeito é imediato.

Header de autenticação

Authorization: Bearer prima_4f8a1c...  (token completo)

Resposta · 401 — token inválido, expirado ou revogado

{
  "message": "Token de integração revogado",
  "error": "Unauthorized",
  "statusCode": 401
}

Segurança do token

· O PRIMA armazena apenas o hash SHA-256 do token — nem a nossa equipe consegue recuperá-lo. Se você perdê-lo, revogue e gere outro.
· Use o token somente em servidor (backend do ERP/integração). Nunca o coloque em aplicativo, site, planilha compartilhada ou repositório de código.
· Guarde-o em variável de ambiente ou cofre de segredos (ex.: PRIMA_API_TOKEN).
· Crie um token por sistema (ERP, BI, middleware) — assim dá para revogar um sem derrubar os demais.
· Em caso de suspeita de vazamento, revogue imediatamente no painel e gere um novo. A revogação vale na hora.

Convenções

Datas e horários

Campos ts/…Em usam ISO 8601 em UTC (sufixo Z). Campos hora são strings no fuso America/Sao_Paulo.

Volumes

Sempre em litros (L), números inteiros ou decimais.

Percentuais

Números decimais — 4.2 significa +4,2%.

Identificadores

Strings opacas (ObjectId). Não interprete o conteúdo, apenas armazene e compare.

Métodos

Somente GET — a API não altera nada na sua conta.

Novos campos

Podem ser adicionados às respostas sem aviso — trate campos desconhecidos de forma tolerante.

Erros e limites

Limite de 120 requisições por minuto por origem. Acima disso a API responde 429 — aplique retry com espera exponencial. Para dados de tempo real, consultar a cada 30–60 s é suficiente (o consolidado tem cache de ~10 s).

200

Sucesso — corpo JSON conforme documentado

400

Parâmetro inválido (ex.: limite não numérico)

401

Token ausente, inválido, expirado ou revogado

404

Recurso inexistente ou de outra empresa

429

Limite de requisições excedido — aguarde e tente novamente

500

Erro interno — tente novamente; persistindo, contate o suporte

Formato padrão de erro

{
  "message": "Descrição do problema",
  "error": "Unauthorized",
  "statusCode": 401
}

Endpoints

Todos relativos à base https://prima.pastu.agr.br/api/v1

GET/ping

Validar token

Confirma que o token é válido e identifica a conta. Use como primeiro teste da integração e como health-check.

Campos principais da resposta

ok	boolean	true quando o token é válido
empresa	string	Nome do laticínio/cooperativa dono do token
token.nome	string	Nome dado ao token no painel
token.expiraEm	string (ISO 8601)	Data de expiração do token
agora	string (ISO 8601)	Relógio do servidor

Requisição

curl -H "Authorization: Bearer prima_SEU_TOKEN" \
  https://prima.pastu.agr.br/api/v1/ping

Resposta · 200 OK

{
  "ok": true,
  "servico": "prima-api",
  "versao": "v1",
  "empresa": "Laticínio Bom Leite",
  "token": {
    "nome": "ERP TOTVS",
    "expiraEm": "2027-09-12T14:00:00.000Z"
  },
  "agora": "2026-09-12T14:32:08.000Z"
}

GET/overview

KPIs consolidados

Fotografia do dia da operação: produção registrada, projeção, volume disponível para coleta e alertas ativos. Atualizada em tempo quase real (cache de ~10 s).

Campos principais da resposta

fazendasConectadas	number	Fazendas vinculadas à empresa
fazendasOnline	number	Fazendas com dados recentes
producaoAgora	number (L)	Litros registrados hoje até agora
variacaoVsMediaPct	number (%)	Hoje vs. média 7d no mesmo horário
producaoProjetada	number (L)	Projeção de fechamento do dia
disponivelColeta	number (L)	Volume em tanque aguardando coleta
fazendasProntas	number	Fazendas com tanque pronto para coleta
alertasAtivos	number	Alertas operacionais abertos
caminhoesEmRota	number	Caminhões em rota neste momento
atualizadoEm	string (ISO 8601)	Momento da consolidação

Requisição

curl -H "Authorization: Bearer prima_SEU_TOKEN" \
  https://prima.pastu.agr.br/api/v1/overview

Resposta · 200 OK

{
  "fazendasConectadas": 9,
  "fazendasOnline": 7,
  "producaoAgora": 8420,
  "variacaoVsMediaPct": 4.2,
  "producaoProjetada": 12480,
  "projecaoVsMediaPct": 2.8,
  "disponivelColeta": 6150,
  "fazendasProntas": 2,
  "fazendasEmOrdenha": 3,
  "alertasAtivos": 1,
  "caminhoesEmRota": 2,
  "atualizadoEm": "2026-09-12T14:32:08.000Z"
}

GET/fazendas

Fazendas (estado atual)

Lista todas as fazendas fornecedoras com produção do dia, tanque, qualidade, status de coleta e itens de estoque em baixa/urgência de reposição. Para os registros de ordenha por vaca, use o detalhe da fazenda.

Campos principais da resposta

id	string	Identificador da fazenda (use no detalhe)
nome / produtor / municipio	string	Identificação da fazenda
coords	objeto { lat, lng }	Localização da fazenda
status	string	ORDENHANDO · PRONTA_COLETA · NORMAL · ALERTA
producaoHoje	number (L)	Litros registrados hoje
tanqueAtual	number (L)	Volume estimado no tanque agora
qualidade	objeto	ccs (mil céls/mL), cbt (mil UFC/mL), gordura (%), proteina (%)
volumeDia	number (L)	Média diária dos últimos 7 dias
score	number (0–100)	Score PRIMA (qualidade + regularidade)
prontoDesde	string \| null	Quando o produtor sinalizou tanque pronto
etaColetaMin	number \| null	Minutos estimados até o caminhão chegar
ultimaColeta	objeto \| null	litrosInformados, volumeReal (medido pelo motorista) e resolvidoEm
estoqueBaixo	objeto \| null	itens[] (id, nome, categoria, quantidadeAtual, quantidadeMinima, unidadeMedida, urgencia: BAIXO\|URGENTE), totalBaixo, totalUrgente — null quando nada está em falta

Requisição

curl -H "Authorization: Bearer prima_SEU_TOKEN" \
  https://prima.pastu.agr.br/api/v1/fazendas

Resposta · 200 OK

[
  {
    "id": "66f1a2b3c4d5e6f7a8b9c0d1",
    "nome": "Fazenda Boa Vista",
    "produtor": "José Almeida",
    "municipio": "Garanhuns",
    "coords": { "lat": -8.8829, "lng": -36.4966 },
    "status": "PRONTA_COLETA",
    "producaoHoje": 1240,
    "tanqueAtual": 980,
    "capacidadeTanque": 0,
    "vacasLactacao": 48,
    "vacasOrdenhadas": 46,
    "variacaoPct": 3.1,
    "qualidade": { "ccs": 210, "cbt": 18, "gordura": 3.9, "proteina": 3.3 },
    "janelaColeta": "09:30 – 10:15",
    "score": 87,
    "volumeDia": 1180,
    "scoreQualidade": 92,
    "scoreRegularidade": 84,
    "crescimentoPct": 2.4,
    "ultimaAtualizacao": "2026-09-12T14:31:40.000Z",
    "prontoDesde": "2026-09-12T13:05:00.000Z",
    "etaColetaMin": 24,
    "chegadaPrevista": "2026-09-12T14:56:00.000Z",
    "ultimaColeta": {
      "litrosInformados": 990,
      "volumeReal": 975,
      "resolvidoEm": "2026-09-11T10:02:00.000Z"
    },
    "estoqueBaixo": {
      "itens": [
        {
          "id": "66f1b2c3d4e5f6a7b8c9d0e1",
          "nome": "Ração concentrada 20%",
          "categoria": "Alimentos",
          "quantidadeAtual": 40,
          "quantidadeMinima": 200,
          "unidadeMedida": "KG",
          "urgencia": "BAIXO"
        }
      ],
      "totalBaixo": 1,
      "totalUrgente": 0
    }
  }
]

GET/fazendas/{id}

Fazenda (detalhe)

Mesmos campos da listagem, mais os últimos registros de ordenha por vaca (campo registros). Retorna 404 se o id não pertencer à sua empresa.

Parâmetros de caminho

string

Id da fazenda obtido em GET /fazendas

Campos principais da resposta

registros[]

array

Últimas ordenhas: vaca (ex.: "#184"), litros, ts (ISO) e hora (HH:mm)

Requisição

curl -H "Authorization: Bearer prima_SEU_TOKEN" \
  https://prima.pastu.agr.br/api/v1/fazendas/66f1a2b3c4d5e6f7a8b9c0d1

Resposta · 200 OK

{
  "id": "66f1a2b3c4d5e6f7a8b9c0d1",
  "nome": "Fazenda Boa Vista",
  "status": "PRONTA_COLETA",
  "producaoHoje": 1240,
  "tanqueAtual": 980,
  "registros": [
    { "vaca": "#184", "litros": 12.4, "ts": "2026-09-12T14:31:40.000Z", "hora": "11:31" },
    { "vaca": "#207", "litros": 9.8, "ts": "2026-09-12T14:29:12.000Z", "hora": "11:29" }
  ]
}

GET/producao/eventos

Eventos de produção

Feed dos últimos registros de ordenha recebidos das fazendas, do mais recente para o mais antigo. Ideal para alimentar filas/integrações incrementais no ERP.

Parâmetros de consulta

limite

number (opcional)

Quantidade de eventos — padrão 50, máximo 200

Campos principais da resposta

id	string	Id único do evento (use para deduplicar)
ts	string (ISO 8601)	Momento do registro
hora	string	HH:mm:ss no fuso America/Sao_Paulo
fazendaId / fazendaNome	string	Origem do evento
vaca	string	Identificação do animal
litros	number (L)	Volume da ordenha

Requisição

curl -H "Authorization: Bearer prima_SEU_TOKEN" \
  https://prima.pastu.agr.br/api/v1/producao/eventos

Resposta · 200 OK

[
  {
    "id": "66f1e0a1b2c3d4e5f6a7b8c9",
    "ts": "2026-09-12T14:31:52.000Z",
    "hora": "11:31:52",
    "fazendaId": "66f1a2b3c4d5e6f7a8b9c0d1",
    "fazendaNome": "Fazenda Boa Vista",
    "vaca": "#184",
    "litros": 12.4
  }
]

GET/produtores

Ranking de produtores

Produtores ordenados pelo score PRIMA (volume, qualidade e regularidade). Útil para bonificação e pagamento por qualidade no ERP.

Campos principais da resposta

posicao	number	Posição no ranking
fazendaId	string	Id da fazenda
score	number (0–100)	Score PRIMA consolidado
volumeDia	number (L)	Média diária 7d
qualidade / regularidade	number (0–100)	Componentes do score
crescimentoPct	number (%)	Média 7d vs. 7d anteriores
producaoHoje	number (L)	Litros de hoje

Requisição

curl -H "Authorization: Bearer prima_SEU_TOKEN" \
  https://prima.pastu.agr.br/api/v1/produtores

Resposta · 200 OK

[
  {
    "posicao": 1,
    "fazendaId": "66f1a2b3c4d5e6f7a8b9c0d1",
    "nome": "Fazenda Boa Vista",
    "produtor": "José Almeida",
    "municipio": "Garanhuns",
    "score": 87,
    "volumeDia": 1180,
    "qualidade": 92,
    "regularidade": 84,
    "crescimentoPct": 2.4,
    "producaoHoje": 1240,
    "status": "NORMAL"
  }
]

GET/rotas

Rotas e frota

Logística de captação em tempo real: usina, caminhões com rota ativa (sequência de paradas, volumes coletado/estimado, próxima parada e ETA) e sugestão de otimização.

Campos principais da resposta

usina	objeto	Nome e coordenadas da unidade de recepção
caminhoes[].placa / motorista	string	Identificação do veículo
caminhoes[].capacidade	number (L)	Capacidade do tanque do caminhão
caminhoes[].volumeColetado	number (L)	Já coletado hoje na rota
caminhoes[].volumeEstimado	number (L)	Restante a coletar (tanques atuais)
caminhoes[].rotaFazendas	string[]	Sequência de paradas da rota
caminhoes[].proximaParada	string	Próximo destino do caminhão
caminhoes[].etaProximaParadaMin	number (min)	Estimativa até a próxima parada
caminhoes[].viagem	string	COLETANDO · RETORNANDO · NA_BASE
otimizacao	objeto	Ganho estimado ao reordenar paradas (km/min)

Requisição

curl -H "Authorization: Bearer prima_SEU_TOKEN" \
  https://prima.pastu.agr.br/api/v1/rotas

Resposta · 200 OK

{
  "usina": {
    "nome": "Unidade principal",
    "coords": { "lat": -8.882, "lng": -36.496 }
  },
  "caminhoes": [
    {
      "id": "66f1c0d1e2f3a4b5c6d7e8f9",
      "nome": "Caminhão 01",
      "placa": "KJU2E11",
      "motorista": "Carlos Lima",
      "capacidade": 15000,
      "volumeEstimado": 6150,
      "volumeColetado": 4890,
      "distanciaKm": 86,
      "tempoRota": "1h55",
      "rotaFazendas": ["Fazenda Boa Vista", "Sítio Riacho Doce"],
      "proximaParada": "Fazenda Boa Vista",
      "etaProximaParadaMin": 24,
      "emRota": true,
      "viagem": "COLETANDO"
    }
  ],
  "otimizacao": {
    "kmEvitados": 12,
    "minEconomizados": 16,
    "litrosAdicionais": 0,
    "mensagem": "Reordenar as paradas reduz a rota de 86 km para 74 km."
  }
}

GET/planejamento

Planejamento de captação (D+1)

Projeção de captação para amanhã por fazenda e por rota: volume previsto, litros em risco, fazendas sem cobertura de rota e capacidade da frota.

Campos principais da resposta

dataAmanha	string (YYYY-MM-DD)	Dia projetado (America/Sao_Paulo)
projecaoAmanha	number (L)	Captação total prevista
litrosEmRisco	number (L)	Volume previsto em fazendas com risco
volumeSemCobertura	number (L)	Previsto em fazendas fora de rota
capacidadeFrota	number (L)	Soma da capacidade dos caminhões ativos
fazendas[]	array	Projeção por fazenda com motivoRisco (SEM_ORDENHA · QUEDA · SEM_ROTA · AGUARDANDO_COLETA)
rotas[]	array	Ocupação projetada por rota, com excedente e paradas que não cabem
porMunicipio[]	array	Resumo por município

Requisição

curl -H "Authorization: Bearer prima_SEU_TOKEN" \
  https://prima.pastu.agr.br/api/v1/planejamento

Resposta · 200 OK

{
  "dataAmanha": "2026-09-13",
  "projecaoAmanha": 12140,
  "tendenciaPct": 1.9,
  "fazendasProjetadas": 9,
  "litrosEmRisco": 1180,
  "fazendasEmRisco": 1,
  "volumeSemCobertura": 640,
  "fazendasSemRota": 1,
  "excedenteRotas": 0,
  "rotasSobrecarregadas": 0,
  "capacidadeFrota": 27000,
  "fazendas": [
    {
      "fazendaId": "66f1a2b3c4d5e6f7a8b9c0d1",
      "nome": "Fazenda Boa Vista",
      "projecaoAmanha": 1215,
      "tendenciaPct": 2.9,
      "cobertura": "EM_ROTA",
      "rotaNome": "Rota Agreste 01",
      "caminhaoNome": "Caminhão 01",
      "litrosEmRisco": 0,
      "motivoRisco": null
    }
  ],
  "rotas": [
    {
      "rotaId": "66f1d0e1f2a3b4c5d6e7f8a9",
      "nome": "Rota Agreste 01",
      "caminhaoNome": "Caminhão 01",
      "capacidade": 15000,
      "paradas": 5,
      "volumeProjetado": 6480,
      "ocupacaoPct": 43,
      "excedente": 0,
      "fazendasExcedentes": []
    }
  ],
  "geradoEm": "2026-09-12T14:32:08.000Z"
}

GET/alertas

Alertas operacionais

Alertas ativos da operação: queda de produção, tanque parado sem coleta, divergência entre volume informado e medido, capacidade de rota, etc.

Campos principais da resposta

tipo	string	queda · acima · coleta · capacidade · sem_coleta · divergencia · divergencia_km · desvio_rota · sem_sinal · parada_fora_rota · coleta_distante · estoque_baixo · estoque_urgente
severidade	string	critico · positivo · info
titulo / descricao / origem	string	Conteúdo do alerta
fazendaId / caminhaoId	string (opcional)	Entidade relacionada

Requisição

curl -H "Authorization: Bearer prima_SEU_TOKEN" \
  https://prima.pastu.agr.br/api/v1/alertas

Resposta · 200 OK

[
  {
    "id": "divergencia-66f1a2b3",
    "tipo": "divergencia",
    "severidade": "critico",
    "titulo": "Divergência informado × medido",
    "origem": "Fazenda Boa Vista",
    "descricao": "Volume medido pelo motorista (975 L) ficou 10,2% abaixo do informado (1.086 L).",
    "hora": "10:05",
    "ts": "2026-09-12T13:05:00.000Z",
    "fazendaId": "66f1a2b3c4d5e6f7a8b9c0d1"
  }
]