Pular para o conteúdo
Typemedia

Documento

API de Parceiros

Atualizado em 09/11/2026

Português · English

Versão 1 · Version 1

Português

Com esta API, o sistema do seu cliente (portal, intranet, painel) lista as peças que a Typemedia mandou para aprovação, mostra os arquivos e registra a decisão: aprovar ou pedir ajuste. O cliente aprova no sistema dele, sem criar conta aqui.

Cada chave pertence a um cliente de uma conta. Ela só enxerga as peças desse cliente.

Autenticação

Envie a chave no cabeçalho Authorization. Quem cria a chave é o titular, sócio ou administrador da conta, em Conta → Integrações de parceiros. A chave aparece uma única vez, no formato tmp_<8 caracteres>_<64 caracteres>. Guarde-a no servidor, nunca em código que o navegador baixa. A chave com o escopo `aprovacoes:decidir` só vale de servidor para servidor: uma chamada do navegador (com cabeçalho Origin) com ela é recusada com 403 chave_so_servidor. Para o navegador, use uma chave só de leitura.

Authorization: Bearer tmp_1a2b3c4d_...

Endereço base: https://typemedia.com.br/api/parceiros/v1

Escopos da chave:

EscopoPermite
aprovacoes:lerListar peças e ver cada peça
aprovacoes:decidirAprovar ou pedir ajuste

Listar peças

GET /pecas?estado=em_aprovacao&limite=50&deslocamento=0

O estado é opcional: em_aprovacao, ajuste_pedido, aprovada, agendada ou publicada. Rascunhos e peças arquivadas nunca aparecem. limite vai até 100.

curl -H "Authorization: Bearer $CHAVE" \
  "https://typemedia.com.br/api/parceiros/v1/pecas?estado=em_aprovacao"
{
  "total": 1, "limite": 50, "deslocamento": 0,
  "dados": [
    { "id": "6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11", "titulo": "Post de abertura", "formato": "post", "canal": "instagram",
      "estado": "em_aprovacao", "data_prevista": "2026-12-01", "versao_atual": 2, "atualizada_em": "2026-11-09T12:00:00+00:00" }
  ]
}

Ver uma peça

GET /pecas/{id}

Traz as versões, a mensagem que a equipe escreveu para o cliente (mensagem), os comentários visíveis ao cliente e os arquivos. Cada arquivo tem uma url assinada que vale por 5 minutos: busque de novo a peça para ter uma URL nova. Notas internas da equipe nunca saem pela API. Peça de outro cliente responde 404, igual a peça que não existe.

curl -H "Authorization: Bearer $CHAVE" \
  https://typemedia.com.br/api/parceiros/v1/pecas/6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11
{
  "id": "6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11", "titulo": "Post de abertura", "estado": "em_aprovacao", "legenda": "Texto da legenda", "versao_atual": 2,
  "versoes": [
    { "numero": 2, "mensagem": "Ajustamos a cor do título.", "criada_em": "2026-11-09T12:00:00+00:00",
      "arquivos": [ { "nome": "post.png", "mime": "image/png", "tamanho": 183204, "url": "https://...", "url_expira_em": "2026-11-09T12:05:00.000Z" } ] }
  ],
  "comentarios": []
}

Decidir

POST /pecas/{id}/decisao

CampoRegra
decisaoaprovar ou ajuste
nomeObrigatório, até 120 caracteres: quem decidiu, no sistema do cliente
comentarioOpcional ao aprovar; obrigatório ao pedir ajuste (até 5000 caracteres)

Só vale para peça em em_aprovacao. A decisão fica registrada com o nome informado e a chave usada.

curl -X POST -H "Authorization: Bearer $CHAVE" -H "Content-Type: application/json" \
  -d '{"decisao":"ajuste","nome":"Maria da Silva","comentario":"Trocar a foto"}' \
  https://typemedia.com.br/api/parceiros/v1/pecas/6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11/decisao
{ "id": "6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11", "estado": "ajuste_pedido", "versao": 2 }

Webhook

Se a chave tiver um endereço de webhook, enviamos um POST com corpo JSON quando uma peça do cliente entra em aprovação (peca.em_aprovacao) ou ganha versão nova enquanto já está em aprovação (peca.versao_nova). Uma versão nova numa peça que estava em ajuste ou aprovada devolve a peça à aprovação e gera um único evento peca.em_aprovacao.

{
  "id": "e2b0f7a4-4c1d-4e0f-a3b7-0d9a1b6f5c22", "evento": "peca.em_aprovacao", "ocorrido_em": "2026-11-09T12:00:00+00:00", "chave_prefixo": "1a2b3c4d",
  "peca": { "id": "6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11", "titulo": "Post de abertura", "formato": "post", "canal": "instagram", "estado": "em_aprovacao", "versao_atual": 2 }
}

O aviso só diz que algo mudou: busque a peça pela API para ver o conteúdo. Cabeçalhos enviados:

CabeçalhoValor
X-Typemedia-Assinaturasha256=<HMAC-SHA256 hexadecimal do corpo, com o segredo do webhook>
X-Typemedia-EventoO evento
X-Typemedia-EntregaO id da entrega, igual ao id do corpo: use para ignorar repetições

Como validar a assinatura (Node.js): calcule o HMAC do corpo exatamente como chegou (antes de converter para objeto) e compare em tempo constante.

import { createHmac, timingSafeEqual } from 'node:crypto';

function assinaturaValida(corpoBruto, cabecalho, segredo) {
  const esperado = 'sha256=' + createHmac('sha256', segredo).update(corpoBruto).digest('hex');
  const a = Buffer.from(esperado), b = Buffer.from(cabecalho ?? '');
  return a.length === b.length && timingSafeEqual(a, b);
}

Compare também ocorrido_em com o relógio do seu servidor e recuse avisos muito antigos. Responda com status 2xx em até 5 segundos. Se falhar, tentamos até 3 vezes (agora, depois de 2 s e depois de 8 s); depois a entrega fica como "Falhou" e pode ser reenviada na tela de Integrações de parceiros. O endereço precisa ser https://, na porta 443, e público (conectamos no IP que conferimos); redirecionamentos não são seguidos. Use id para tratar repetições.

Limites e CORS

  • 120 chamadas por minuto por chave. Acima disso: 429 com o cabeçalho Retry-After (segundos). Cada resposta traz X-RateLimit-Limit e X-RateLimit-Remaining.
  • Chamadas de servidor não precisam de CORS. Para chamar do navegador, cadastre o site da chave (por exemplo https://portal.exemplo.com.br); só essas origens recebem Access-Control-Allow-Origin. Não existe *. Do navegador só funcionam chaves de leitura: a chave com aprovacoes:decidir é recusada (chave_so_servidor) e a decisão deve ser enviada pelo seu servidor. Prefira sempre chamar do seu servidor, para não expor a chave.
  • Tentativas com chave inválida são limitadas por endereço IP (60 por minuto): acima disso, 429.

Erros

Todo erro vem como { "erro": { "codigo": "...", "mensagem": "..." } }.

StatusCódigoQuando
400estado_invalido, parametros_invalidos, json_invalido, decisao_invalidaPedido mal formado
401nao_autorizado, chave_invalida, chave_revogada, chave_inativaChave ausente, errada, revogada ou sem cliente ativo
403sem_escopo, origem_nao_permitida, chave_so_servidorChave sem o escopo, origem não cadastrada, ou chave que decide usada do navegador
404peca_nao_encontradaPeça inexistente ou de outro cliente
409peca_nao_esta_em_aprovacaoA peça não está esperando decisão
422nome_obrigatorio, comentario_obrigatorio, comentario_longoDados da decisão
429limite_excedidoPassou do limite por minuto
500falha_internaTente de novo

Rede, v1 (contrato, sem implementação)

> Estado: contrato, não serviço. Nada desta seção responde ainda: os caminhos abaixo existem só para o domínio de quem contrata (organização, governo, negócio com propósito) poder ser construído sobre eles. Hoje devolvem 404. A implementação começa quando esse domínio for aberto; até lá, o contrato só muda de forma compatível e a mudança entra aqui antes de entrar no código.

Estende esta API para as oportunidades, candidaturas, contratos, marcos e avaliações da rede. Quem usa o quê: quem publica e contrata publica a oportunidade, escolhe quem candidatou, aprova a entrega, registra o pagamento e avalia; quem presta o serviço candidata, entrega e avalia. As regras (quem pode, em que estado, qual limite do plano) ficam no banco e são as mesmas das telas: a API não tem regra própria.

Autenticação e chave. Mesmo cabeçalho Authorization: Bearer tmp_... e mesmo formato de chave. A diferença: a chave da rede é presa a uma conta (não a um cliente) e age em nome dela. O que a conta não pode fazer na tela (conta sem verificação, vínculo pendente, limite do plano) a chave também não pode. Mesma gestão, na tela Conta → Integrações de parceiros; mesmo limite_por_minuto, mesmas origens e mesma regra de CORS.

EscopoPermite
rede:lerListar e ver oportunidades, candidaturas, contratos, marcos e avaliações da conta
rede:escreverPublicar, candidatar, escolher, responder contrato, entregar, decidir entrega, registrar pagamento e avaliar

Nome antigo. Estes escopos se chamavam marketplace:ler e marketplace:escrever. O nome antigo continua aceito por enquanto, como equivalente do novo: chave que já o tem segue valendo, e a criação de chave nova oferece só rede:ler e rede:escrever.

Como na decisão de peças, uma chave com rede:escrever só vale de servidor para servidor: com Origin ou Sec-Fetch-Site é recusada com 403 chave_so_servidor. Um mesmo pedido nunca troca de conta: o id de um recurso de outra conta responde 404, igual ao que não existe.

Paginação, formatos e repetição. Toda lista aceita limite (até 100) e deslocamento e responde { "total", "limite", "deslocamento", "dados": [...] }. Datas em ISO 8601, valores em reais como número com duas casas. Todo POST aceita o cabeçalho Idempotency-Key (texto de até 64 caracteres): repetir a mesma chave devolve a primeira resposta sem refazer a ação.

RecursoMétodo e caminhoEscopoQuem usaO que faz
OportunidadesGET /oportunidadeslertodosOportunidades abertas, só campos públicos. A lista segue o plano da conta da chave (nível e atraso de exibição), como na tela
GET /oportunidades/{id}lertodosUma oportunidade aberta ou da própria conta
POST /oportunidadesescreverquem publicaPublica oportunidade
POST /oportunidades/{id}/fechamentoescreverquem publicaFecha a oportunidade (fechada)
CandidaturasGET /oportunidades/{id}/candidaturaslerquem publicaCandidaturas recebidas da própria oportunidade
POST /oportunidades/{id}/candidaturasescreverquem prestaCandidata a conta da chave
GET /candidaturaslertodosCandidaturas enviadas ou recebidas pela conta
POST /candidaturas/{id}/escolhaescreverquem publicaEscolhe a candidatura e cria o contrato com os marcos
ContratosGET /contratoslertodosContratos em que a conta é parte; filtro estado
GET /contratos/{id}lertodosContrato com marcos e histórico
POST /contratos/{id}/respostaescrevera parte que ainda não respondeuAceita ou recusa o contrato
MarcosGET /contratos/{id}/marcoslertodosMarcos e a entrega mais recente de cada um
POST /marcos/{id}/arquivosescreverquem prestaReserva envio de arquivo da entrega (URL assinada de envio)
POST /marcos/{id}/entregaescreverquem prestaEntrega o marco
POST /entregas/{id}/decisaoescreverquem contrataAprova ou pede ajuste
POST /marcos/{id}/pagamentoescreverquem contrataRegistra o pagamento do marco aprovado
AvaliaçõesGET /contratos/{id}/avaliacoeslertodosAvaliações visíveis para a conta (regra às cegas)
POST /contratos/{id}/avaliacoesescrevertodosAvalia o contrato num momento
DiretórioGET /diretorio?cnpj=<14 dígitos>lertodosUma organização por CNPJ exato, só campos públicos. Só existe no diretório quem criou conta, reivindicou o perfil e está ativo: qualquer outro CNPJ responde 404
AcompanhamentosGET /acompanhamentoslerquem prestaTrabalhos fechados da conta da chave, com o estado de cada um; filtro estado
GET /acompanhamentos/{id}lerquem prestaUm trabalho com os marcos e o estado de cada um; sem dados do cliente além do nome

Oportunidades

Os campos são os mesmos que a tela mostra a quem lê o feed; conta_id e dados internos não saem.

curl -H "Authorization: Bearer $CHAVE" \
  "https://typemedia.com.br/api/parceiros/v1/oportunidades?limite=20"
{
  "total": 1, "limite": 20, "deslocamento": 0,
  "dados": [
    { "id": "b3a1d0f2-5c47-4e8a-9a1e-7c2d4f6b8e10", "conta_nome": "Instituto Exemplo", "titulo": "Identidade visual para festival",
      "descricao": "Logotipo, paleta e aplicações básicas.", "area": "design", "nivel": "aberta",
      "valor_estimado": 8000.00, "prazo": "2026-12-20", "modalidade": "remoto", "local": null,
      "projeto_nome": "Festival Exemplo 2027", "criado_em": "2026-11-10T14:00:00+00:00" }
  ]
}

nivel é aberta ou verba_aprovada. Publicar:

POST /oportunidades com titulo (até 200 caracteres), descricao (até 5000), area, valor_estimado, prazo, modalidade (remoto, presencial ou hibrido), local, projeto_id (projeto público da própria conta) e nivel. Responde 201 com a oportunidade.

{ "titulo": "Identidade visual para festival", "descricao": "Logotipo, paleta e aplicações básicas.", "area": "design",
  "valor_estimado": 8000.00, "prazo": "2026-12-20", "modalidade": "remoto", "nivel": "aberta" }

Candidaturas e escolha

POST /oportunidades/{id}/candidaturas com mensagem (até 3000 caracteres), valor_proposto e portfolio_url. Responde 201 com { "id", "estado": "enviada" }. O estado de uma candidatura é enviada, escolhida, recusada ou retirada. Cada conta se candidata uma vez por oportunidade (409 candidatura_repetida).

POST /candidaturas/{id}/escolha com o escopo e a lista de marcos (cada um com titulo, valor e data_prevista). Cria o contrato, que nasce proposto, e recusa as demais candidaturas da oportunidade.

{ "escopo": "Logotipo, paleta e aplicações básicas, em duas rodadas de ajuste.",
  "marcos": [ { "titulo": "Conceito aprovado", "valor": 3000.00, "data_prevista": "2026-12-01" },
              { "titulo": "Arquivos finais", "valor": 5000.00, "data_prevista": "2026-12-20" } ] }

Contratos

Estados: proposto (espera a resposta de quem presta), aguardando_contratante (nasce de proposta comercial; só a contratante responde), ativo, concluido, cancelado e recusado. Contrato é permissão financeira: a conta precisa estar verificada, senão 403 conta_nao_verificada.

{
  "id": "0d9e7c44-2f1b-4a60-8b35-91c3a5e7d2f8", "titulo": "Identidade visual para festival", "estado": "proposto",
  "contratante_nome": "Instituto Exemplo", "profissional_nome": "Ana Exemplo", "valor_total": 8000.00,
  "oportunidade_id": "b3a1d0f2-5c47-4e8a-9a1e-7c2d4f6b8e10", "criado_em": "2026-11-10T15:00:00+00:00",
  "marcos": [ { "id": "e1f2a3b4-0000-4c11-9d22-aaaabbbbcccc", "titulo": "Conceito aprovado", "valor": 3000.00, "estado": "a_fazer", "data_prevista": "2026-12-01", "pago_em": null } ],
  "historico": [ { "texto": "Contrato proposto", "autor_nome": "Instituto Exemplo", "criado_em": "2026-11-10T15:00:00+00:00" } ]
}

POST /contratos/{id}/resposta com { "decisao": "aceitar" } ou { "decisao": "recusar", "motivo": "..." }. A API escolhe a regra certa pela posição da conta no contrato. A taxa que a plataforma cobra não faz parte do contrato da API: ela é regra da plataforma, definida no banco no momento da escolha, e não aparece nem se altera por aqui.

Marcos, entregas e pagamento

Estados do marco: a_fazer, entregue, aprovado, pago. O contrato vira concluido quando o último marco é pago.

  • POST /marcos/{id}/arquivos com { "nome", "mime", "tamanho" } devolve { "caminho", "url_envio", "url_envio_expira_em" }: envie o arquivo com PUT na url_envio (vale 5 minutos) e use o caminho na entrega.
  • POST /marcos/{id}/entrega com { "nota": "...", "arquivos": [ { "caminho": "..." } ] }. Só marco a_fazer de contrato ativo. Responde 201 com { "entrega_id" }.
  • POST /entregas/{id}/decisao com { "decisao": "aprovada" | "ajuste", "comentario": "..." }; o comentário é obrigatório no ajuste.
  • POST /marcos/{id}/pagamento registra que o pagamento foi feito fora da plataforma. A API não movimenta dinheiro. Só marco aprovado.

Avaliações

POST /contratos/{id}/avaliacoes com momento (fechamento ou entrega), nps (0 a 10), nota_contraparte (1 a 5) e porque. Uma por conta, contrato e momento (409 avaliacao_repetida).

Visibilidade às cegas. O GET devolve sempre a avaliação da própria conta. A nota_contraparte e o porque da outra parte só aparecem quando as duas contas responderam ao mesmo momento ou 14 dias depois da primeira resposta (liberada_em). Antes disso o campo vem null. O nps da plataforma nunca é mostrado à contraparte.

{ "dados": [
  { "momento": "fechamento", "de": "propria", "nps": 9, "nota_contraparte": 5, "porque": "Briefing claro.", "criada_em": "2026-11-12T10:00:00+00:00", "liberada_em": null },
  { "momento": "fechamento", "de": "contraparte", "nota_contraparte": null, "porque": null, "criada_em": "2026-11-12T11:00:00+00:00", "liberada_em": null }
] }

Diretório e acompanhamentos

Contrato, ainda sem implementação, como o resto desta seção. Os dois recursos seguem a regra da rede: o diretório só tem quem criou conta, reivindicou o perfil e está ativo. Uma organização que nunca criou conta não existe para a API, mesmo que o CNPJ dela seja conhecido por outra origem.

GET /diretorio?cnpj=<14 dígitos> (escopo rede:ler). Devolve uma entidade pelo CNPJ exato, só com campos públicos. Não há lista, não há busca por nome e não há exportação: sem o parâmetro cnpj, ou com um CNPJ de organização que não está na rede, a resposta é 404 entidade_nao_encontrada; CNPJ malformado dá 422 cnpj_invalido.

{ "cnpj": "11222333000181", "tipo": "organizacao", "nome": "Instituto Exemplo", "municipio": "Brasília", "uf": "DF", "area": "Cultura", "na_rede": true }

tipo é organizacao, empresa ou orgao. na_rede é sempre true (a resposta só existe para quem está na rede). Nunca saem e-mail, telefone, nome de pessoa nem endereço completo.

GET /acompanhamentos e GET /acompanhamentos/{id} (escopo rede:ler). São os trabalhos fechados da conta da chave, os mesmos que ela vê na ficha do cliente. Mostram o título, o estado (ativo, concluido ou cancelado), se o cliente já confirmou pelo link, os marcos e o estado de cada um (a_fazer, entregue, ajuste_pedido, aprovado) e o nome do cliente. Não saem valor, contato, CNPJ nem notas do cliente; o id de um trabalho de outra conta responde 404 acompanhamento_nao_encontrado.

{
  "id": "5d1f7a52-3c80-4e0b-8c1c-2a6a8f9b4e10", "titulo": "Site novo", "estado": "ativo", "fechado_em": "2026-11-10",
  "confirmado_pelo_cliente": true, "cliente_nome": "Associação Exemplo",
  "marcos": [
    { "titulo": "Layout", "data_prevista": "2026-12-01", "estado": "aprovado" },
    { "titulo": "No ar", "data_prevista": null, "estado": "a_fazer" }
  ]
}

O link que o cliente recebe não é um recurso desta API: ele abre uma página própria, sem conta, e a plataforma não o envia (quem presta o serviço envia, pelo canal dela).

Avisos (webhook)

Quando a chave tem URL de webhook, os eventos abaixo seguem o mesmo envelope, a mesma assinatura HMAC e a mesma política de tentativas do webhook de peças. Como lá, o aviso só diz que algo mudou: busque o recurso pela API.

EventoQuando
oportunidade.candidatura_recebidaChegou candidatura numa oportunidade da conta
candidatura.escolhida / candidatura.recusadaA conta candidata foi escolhida ou não
contrato.proposto, contrato.ativo, contrato.recusadoO contrato mudou de estado
marco.entregue, entrega.decidida, marco.pagoAndamento de um marco
avaliacao.liberadaA avaliação da contraparte ficou legível

Erros da rede

Mesmo formato de erro da seção acima, mais estes códigos.

StatusCódigoQuando
403conta_nao_verificada, sem_permissao, plano_nao_permiteConta sem verificação, sem permissão para a ação ou fora do plano
404oportunidade_nao_encontrada, candidatura_nao_encontrada, contrato_nao_encontrado, marco_nao_encontrado, entrega_nao_encontrada, entidade_nao_encontrada, acompanhamento_nao_encontradoInexistente, de outra conta ou, no diretório, organização que não está na rede
409candidatura_repetida, oportunidade_fechada, estado_invalido, avaliacao_repetidaA ação não cabe no estado atual
422limite_candidaturas, valor_invalido, marcos_invalidos, nps_invalido, comentario_obrigatorio, cnpj_invalidoDados da ação ou limite do plano

English

This API lets your client's own system (portal, intranet, dashboard) list the pieces Typemedia sent for approval, show their files and record the decision: approve, or request changes. The client approves in their own system and never needs an account here.

Each key belongs to one client of one account, and only sees that client's pieces.

Authentication

Send the key in the Authorization header. The account owner, partner or administrator creates keys under Conta → Integrações de parceiros. The key is shown once, as tmp_<8 chars>_<64 chars>. Keep it on your server, never in code the browser downloads. A key with the aprovacoes:decidir scope only works server to server: a browser call (with an Origin header) using it is refused with 403 chave_so_servidor; for browsers use a read-only key.

Authorization: Bearer tmp_1a2b3c4d_...

Base URL: https://typemedia.com.br/api/parceiros/v1

Key scopes: aprovacoes:ler (list and read pieces) and aprovacoes:decidir (approve or request changes).

List pieces

GET /pecas?estado=em_aprovacao&limite=50&deslocamento=0

estado is optional: em_aprovacao (awaiting approval), ajuste_pedido (changes requested), aprovada, agendada or publicada. Drafts and archived pieces never appear. limite (page size) goes up to 100; deslocamento is the offset.

curl -H "Authorization: Bearer $KEY" \
  "https://typemedia.com.br/api/parceiros/v1/pecas?estado=em_aprovacao"

The response has total, limite, deslocamento and dados, an array of pieces (id, titulo, formato, canal, estado, data_prevista, versao_atual, atualizada_em).

Read a piece

GET /pecas/{id}

Returns versions, the message the team wrote for the client (mensagem), the comments visible to the client, and the files. Each file has a signed url valid for 5 minutes; fetch the piece again for a fresh URL. Internal team notes never leave the API. A piece of another client answers 404, the same as a piece that does not exist.

curl -H "Authorization: Bearer $KEY" \
  https://typemedia.com.br/api/parceiros/v1/pecas/6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11

Decide

POST /pecas/{id}/decisao with JSON { "decisao": "aprovar" | "ajuste", "nome": "...", "comentario": "..." }.

nome is required (who decided, up to 120 characters). comentario is optional when approving and required when requesting changes (up to 5000 characters). It only works while the piece is em_aprovacao. The decision is recorded with the given name and the key used.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"decisao":"aprovar","nome":"Maria da Silva"}' \
  https://typemedia.com.br/api/parceiros/v1/pecas/6f1c0c1e-8a52-4a38-9d5e-2f6b7d0a1c11/decisao

The response is { "id": "...", "estado": "aprovada" | "ajuste_pedido", "versao": 2 }.

Webhook

If the key has a webhook URL, we send a JSON POST when a piece of that client enters approval (peca.em_aprovacao) or receives a new version while already in approval (peca.versao_nova). A new version on a piece that was in changes-requested or approved state returns it to approval and produces a single peca.em_aprovacao event. The body is shown in the Portuguese section above. The notice only says something changed: fetch the piece through the API for its content.

Headers: X-Typemedia-Assinatura: sha256=<hex HMAC-SHA256 of the raw body using the webhook secret>, X-Typemedia-Evento (the event) and X-Typemedia-Entrega (delivery id, equal to the body id; use it to ignore repeats).

Verifying the signature (Node.js): compute the HMAC over the body exactly as received (before parsing) and compare in constant time, as in the code sample above. Also check ocorrido_em against your clock and reject stale notices. Answer with a 2xx status within 5 seconds. On failure we retry up to 3 times in total (now, after 2 s, after 8 s); then the delivery is marked "Falhou" and can be resent from the screen. The URL must be public https:// on port 443 (we connect to the IP we checked); redirects are not followed.

Limits and CORS

  • 120 calls per minute per key. Beyond that: 429 with Retry-After (seconds). Every response carries X-RateLimit-Limit and X-RateLimit-Remaining.
  • Server-to-server calls need no CORS. To call from a browser, register your site (for example https://portal.example.com) on the key; only those origins get Access-Control-Allow-Origin. There is no *. Only read keys work from a browser: a key with aprovacoes:decidir is refused (chave_so_servidor); send decisions from your server. Always prefer calling from your server so the key is not exposed.
  • Attempts with an invalid key are limited per IP address (60 per minute): beyond that, 429.

Errors

Every error is { "erro": { "codigo": "...", "mensagem": "..." } }. Status codes: 400 malformed request (estado_invalido, parametros_invalidos, json_invalido, decisao_invalida); 401 missing, wrong, revoked or inactive key (nao_autorizado, chave_invalida, chave_revogada, chave_inativa); 403 missing scope, unregistered origin, or a deciding key used from a browser (sem_escopo, origem_nao_permitida, chave_so_servidor); 404 piece not found or of another client (peca_nao_encontrada); 409 piece not awaiting a decision (peca_nao_esta_em_aprovacao); 422 invalid decision data (nome_obrigatorio, comentario_obrigatorio, comentario_longo); 429 rate limit (limite_excedido); 500 falha_interna.

Network, v1 (contract, not implemented)

> Status: a contract, not a service. Nothing in this section responds yet; the paths exist so the domain of those who hire (organizations, government, purpose-driven businesses) can be built on them. Today they return 404. Implementation starts when that domain opens; until then the contract only changes compatibly, and the change lands here before it lands in code.

This extends the API to the network's opportunities, applications, contracts, milestones and reviews. Whoever publishes and hires posts the opportunity, picks an applicant, approves deliveries, records payment and reviews; whoever provides the service applies, delivers and reviews. Rules (who may, in which state, which plan limit) live in the database and are the same as in the screens: the API has no rules of its own.

Authentication and key. Same Authorization: Bearer tmp_... header and key format. Difference: a network key is bound to one account (not a client) and acts on its behalf. What the account cannot do on screen (unverified account, pending membership, plan limit) the key cannot do either. Same management screen (Account → Partner integrations), same limite_por_minuto, origens and CORS rule.

ScopeAllows
rede:lerList and read the account's opportunities, applications, contracts, milestones and reviews
rede:escreverPublish, apply, choose, answer a contract, deliver, decide a delivery, record payment and review

Old name. These scopes used to be called marketplace:ler and marketplace:escrever. The old name is still accepted for now as equivalent to the new one: a key that already has it keeps working, and creating a new key offers only rede:ler and rede:escrever.

As with piece decisions, a key with rede:escrever only works server to server: with Origin or Sec-Fetch-Site it is refused with 403 chave_so_servidor. A request never switches accounts: the id of another account's resource returns 404, like a missing one.

Pagination, formats and retries. Every list takes limite (up to 100) and deslocamento and answers { "total", "limite", "deslocamento", "dados": [...] }. Dates are ISO 8601; amounts are numbers with two decimals (BRL). Every POST accepts an Idempotency-Key header (text up to 64 characters): repeating a key returns the first response without redoing the action.

Endpoints (all under /api/parceiros/v1):

  • Opportunities: GET /oportunidades and GET /oportunidades/{id} (read; open ones, public fields only, filtered by the plan of the key's account as in the screen); POST /oportunidades and POST /oportunidades/{id}/fechamento (write; publisher).
  • Applications: GET /oportunidades/{id}/candidaturas (read; publisher); POST /oportunidades/{id}/candidaturas (write; provider); GET /candidaturas (read; sent or received); POST /candidaturas/{id}/escolha (write; publisher; creates the contract with its milestones).
  • Contracts: GET /contratos (filter estado) and GET /contratos/{id} (read; with milestones and history); POST /contratos/{id}/resposta (write; the party that has not answered; { "decisao": "aceitar" } or { "decisao": "recusar", "motivo": "..." }).
  • Milestones: GET /contratos/{id}/marcos (read); POST /marcos/{id}/arquivos (write; provider; returns a signed upload URL valid for 5 minutes); POST /marcos/{id}/entrega (write; provider); POST /entregas/{id}/decisao (write; hiring side; aprovada or ajuste, comment required for ajuste); POST /marcos/{id}/pagamento (write; hiring side; records a payment made outside the platform, which never moves money; approved milestones only).
  • Directory: GET /diretorio?cnpj=<14 digits> (read; one organization by exact CNPJ, public fields only: cnpj, tipo, nome, municipio, uf, area, na_rede). The directory only has organizations that created an account, claimed their profile and are active; any other CNPJ answers 404 entidade_nao_encontrada and a malformed one 422 cnpj_invalido. No list, no search by name, no export.
  • Engagements: GET /acompanhamentos and GET /acompanhamentos/{id} (read; the work closed with clients by the key's account, with title, state ativo, concluido or cancelado, whether the client confirmed through the link, milestones and the state of each one, and the client's name only; no amount, contact, CNPJ or notes; another account's id answers 404 acompanhamento_nao_encontrado). The link the client receives is not part of this API: it opens its own page, with no account.
  • Reviews: GET /contratos/{id}/avaliacoes (read) and POST /contratos/{id}/avaliacoes (write; momento fechamento or entrega, nps 0 to 10, nota_contraparte 1 to 5, porque; one per account, contract and moment).

Opportunity fields (same as the screen shows to feed readers; conta_id and internal data never leave): id, conta_nome, titulo, descricao, area, nivel (aberta or verba_aprovada), valor_estimado, prazo, modalidade (remoto, presencial, hibrido), local, projeto_nome, criado_em. Request and response examples are in the Portuguese section above; field names are identical.

Contract states: proposto (waiting for the provider), aguardando_contratante (born from a commercial proposal; only the hiring account answers), ativo, concluido, cancelado, recusado. Contracts are a financial permission: the account must be verified, otherwise 403 conta_nao_verificada. Milestone states: a_fazer, entregue, aprovado, pago; the contract becomes concluido when the last milestone is pago. The fee the platform charges is not part of the API contract: it is a platform rule set in the database when the applicant is chosen, and it neither appears nor changes through the API.

Blind reviews. GET always returns the account's own review. The other party's nota_contraparte and porque become readable only when both accounts have answered the same moment or 14 days after the first answer (liberada_em); until then the fields are null. The platform nps is never shown to the counterpart.

Notices (webhook). If the key has a webhook URL, these events use the same envelope, HMAC signature and retry policy as the piece webhook, and only say that something changed: oportunidade.candidatura_recebida, candidatura.escolhida, candidatura.recusada, contrato.proposto, contrato.ativo, contrato.recusado, marco.entregue, entrega.decidida, marco.pago, avaliacao.liberada.

Network errors, in the same format, besides those above: 403 conta_nao_verificada, sem_permissao, plano_nao_permite; 404 oportunidade_nao_encontrada, candidatura_nao_encontrada, contrato_nao_encontrado, marco_nao_encontrado, entrega_nao_encontrada, entidade_nao_encontrada, acompanhamento_nao_encontrado; 409 candidatura_repetida, oportunidade_fechada, estado_invalido, avaliacao_repetida; 422 limite_candidaturas, valor_invalido, marcos_invalidos, nps_invalido, comentario_obrigatorio, cnpj_invalido.

Política de privacidadeTermos de usoExclusão de dadoscontato@typemedia.com.br