Regras, erros e dúvidas

Esta página reúne o que é permitido ao criar uma assinatura/rubrica posicionada, os erros que a API retorna quando uma regra não é atendida e as dúvidas mais comuns. As regras valem para os três endpoints: requirements, bulk_requirements e envelope_bulk_creations.

Para ver os fluxos completos, acesse a página de Tutorial de uso.

Uma forma de posicionamento por rubrica

Cada requisito de rubrica define o lugar da rubrica de uma única forma. Por isso, positions é mutuamente exclusivo com os outros dois campos de rubrica:

Se o mesmo requisito trouxer positions junto com pages ou com rubric_field, a API recusa a requisição inteira com 400 Bad Request e não cria nada.

Não pode: positions com pages

"attributes": {
  "action": "rubricate",
  "kind": "initials",
  "positions": [ { "page": "1", "position": [0.85, 0.9] } ],
  "pages": "all"
}

Não pode: positions com rubric_field

"attributes": {
  "action": "rubricate",
  "kind": "initials",
  "positions": [ { "page": "1", "position": [0.85, 0.9] } ],
  "rubric_field": "position_sign_signer"
}

Os dois casos retornam o mesmo erro. O pointer sempre aponta para positions, e o prefixo muda conforme o endpoint:

requirements:

{ "errors": [ { "code": "bad_request", "status": 400, "source": { "pointer": "/data/attributes/positions" }, "detail": "positions não pode ser enviado junto com 'pages' ou 'rubric_field'" } ] }

bulk_requirements (operação de índice 0):

{ "errors": [ { "code": "bad_request", "status": 400, "source": { "pointer": "/atomic:operations/0/data/attributes/positions" }, "detail": "positions não pode ser enviado junto com 'pages' ou 'rubric_field'" } ] }

envelope_bulk_creations (signatário 0, requisito 2):

{ "errors": [ { "code": "bad_request", "status": 400, "source": { "pointer": "/data/attributes/signers/0/requirements/2/positions" }, "detail": "positions não pode ser enviado junto com 'pages' ou 'rubric_field'" } ] }

Pode: requisitos separados, um de cada kind

Para combinar formas diferentes no mesmo signatário, crie um requisito para cada uma, com kind diferentes:

"requirements": [
  { "action": "agree", "role": "sign" },
  { "action": "provide_evidence", "auth": "email" },
  { "action": "rubricate", "kind": "initials", "pages": "all" },
  { "action": "rubricate", "kind": "manuscript", "positions": [ { "page": "1", "position": [0.2, 0.2] } ] }
]

Regras de validação

Erros comuns

Respostas reais do endpoint de requisitos (o pointer indica o campo com problema):

page como número ("page": 1) → 400 Bad Request

{ "errors": [ { "code": "bad_request", "status": 400, "source": { "pointer": "/data/attributes/positions/0/page" }, "detail": "page deve ser uma string" } ] }

Coordenadas em pixels ("position": [120, 300]) → 400 Bad Request

{
  "errors": [
    { "code": "bad_request", "status": 400, "source": { "pointer": "/data/attributes/positions/0/position/0" }, "detail": "0 deve ser menor ou igual a 1" },
    { "code": "bad_request", "status": 400, "source": { "pointer": "/data/attributes/positions/0/position/1" }, "detail": "1 deve ser menor ou igual a 1" }
  ]
}

Só uma coordenada ("position": [0.5]) → 400 Bad Request

{ "errors": [ { "code": "bad_request", "status": 400, "source": { "pointer": "/data/attributes/positions/0/position" }, "detail": "position tamanho deve ser 2" } ] }

Lista vazia ("positions": []) → 400 Bad Request

{ "errors": [ { "code": "bad_request", "status": 400, "source": { "pointer": "/data/attributes/positions" }, "detail": "positions tamanho não deve ser menor que 1" } ] }

Segunda rubrica do mesmo kind para o mesmo signatário e documento → 422 Unprocessable Entity

{ "errors": [ { "title": "já está em uso", "detail": "action - já está em uso", "code": "100", "source": { "pointer": "/data/attributes/action" }, "status": "422" } ] }

Nos outros endpoints, as regras são as mesmas e o pointer muda de prefixo:

Nos endpoints de lote, os erros também mudam na forma como são aplicados:

Dúvidas frequentes

Onde fica o ponto [0, 0]?
No canto superior esquerdo da página. x cresce para a direita e y cresce para baixo.

Posso usar a mesma coordenada em documentos de tamanhos diferentes?
Sim. Como os valores são proporções da página, [0.85, 0.9] fica sempre perto do canto inferior direito.

Como mudo a posição de uma rubrica já criada?
Exclua o requisito (DELETE /api/v3/envelopes/{envelope_id}/requirements/{requirement_id}) e crie outro, ou faça as duas coisas numa chamada de bulk_requirements (veja o exemplo). O endpoint de requisitos só aceita alterações com o envelope em rascunho (draft); o bulk_requirements aceita também envelopes já ativados (running).

Um signatário pode ter rubrica de iniciais e manuscrita no mesmo documento?
Sim, uma de cada kind.

Posso enviar positions e pages (ou rubric_field) no mesmo requisito?
Não. Cada requisito de rubrica usa uma só forma, e a combinação retorna 400 (veja o exemplo). Para usar formas diferentes, crie requisitos separados com kind diferentes.

A resposta do envelope_bulk_creations traz a rubrica?
Não. Ela traz o job_id. Consulte os requisitos do envelope depois que ele for criado (veja o exemplo).

Consigo ver um caso de uso executável?
Sim, temos um passo a passo detalhado nessa página.

Referência da API:

• Criar Requisito de Rubrica
• Criação e Exclusão de Requisitos
• Criar Envelope em Lote