> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niadra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Perguntar antes de agir

> A decisão de coordenação para uma intenção: `allow`, `defer`, `deny` ou `handoff_to`, com quem detém o cliente, o estado do efeito, o canal, o orçamento de contato e, quando a finalidade pede, o token de contato. Escopo `coordinate`; funcionalidade `coordination`.



## OpenAPI

````yaml openapi/pt/cell.json POST /v1/coordination/check
openapi: 3.1.0
info:
  title: API de dados da Niadra
  version: '1'
  description: >-
    Escrita, contexto, histórico, objetos, identidade, privacidade e governança
    de um espaço. Cada espaço tem um endereço estável, com o espaço e a região
    no nome.
servers:
  - url: https://{space}.{region}.api.niadra.com
    variables:
      space:
        default: acme-prod
        description: O espaço, que vem na chave de fonte.
      region:
        default: us-east-2
        description: A região do espaço, que também vem na chave.
security: []
paths:
  /v1/coordination/check:
    post:
      tags:
        - coordination
      summary: Perguntar antes de agir
      description: >-
        Pergunta se o agente pode agir agora, antes de agir. O produtor avalia
        em ordem e para no primeiro que decide: a chave do efeito (feita, em voo
        ou ambígua nega), uma supressão da finalidade, um detentor cuja
        reivindicação não permite a intenção, a trava de outro detentor sobre a
        tarefa, um orçamento esgotado ou ritmado, o horário de silêncio. Só
        então o orçamento é gasto e, para uma finalidade que precisa, o token de
        contato é emitido. Uma mensagem que o cliente mandou nunca é negada. Com
        `effect_key`, um `allow` cujo `effect.state` é `none` também reservou o
        efeito: aja e depois declare como terminou.


        **Autenticação.** Chave de fonte: `Authorization: Bearer nia_sk_...`.
        Escopo exigido: `coordinate`. Só responde num espaço com a
        funcionalidade `coordination` ligada (o documento `features`); num
        espaço sem ela, 404.
      operationId: check_v1_coordination_check_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CheckRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckResult'
          description: >-
            A decisão, válida por `valid_for_s` segundos; quem age depois disso
            pergunta de novo.
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
          description: O pedido não bate com o contrato.
      security:
        - sourceKey: []
      x-codeSamples:
        - lang: python
          label: Python
          source: >-
            # Ask before an outbound contact; with Niadra out of reach the
            purpose decides (marketing waits)

            decision = conversation.check("proposal_followup",
            purpose="marketing", channel="whatsapp")

            if decision.decision == "allow":
                gateway.send(message, token=decision.contact_token)
                conversation.declare.contact_made(decision, purpose="marketing", channel="whatsapp")
        - lang: typescript
          label: TypeScript
          source: >-
            // Ask before an outbound contact; with Niadra out of reach the
            purpose decides (marketing waits)

            const decision = await convo.check("proposal_followup", { purpose:
            "marketing", channel: "whatsapp" });

            if (decision.decision === "allow") {
              await gateway.send(message, { token: decision.contact_token });
              convo.declare.contactMade(decision, { purpose: "marketing", channel: "whatsapp" });
            }
components:
  schemas:
    CheckRequest:
      additionalProperties: false
      description: >-
        O que um agente está prestes a fazer. Sem cliente não há orçamento,
        supressão nem detentor a consultar: uma pergunta assim só trata da chave
        do efeito.
      properties:
        agent:
          maxLength: 256
          minLength: 1
          title: Agent
          type: string
        channel:
          anyOf:
            - pattern: ^[a-z][a-z0-9_]{0,39}$
              type: string
            - type: 'null'
          title: Channel
        destination_hash:
          anyOf:
            - pattern: ^[A-Za-z0-9_-]{43}$
              type: string
            - type: 'null'
          description: >-
            O `rcpt` do token, calculado por quem tem a chave do gateway, quando
            o destino não é o handle do cliente.
          title: Destination Hash
        direction:
          enum:
            - inbound
            - outbound
          title: Direction
          type: string
        effect_key:
          anyOf:
            - maxLength: 512
              minLength: 1
              type: string
            - type: 'null'
          description: >-
            A chave do fato de negócio; reservada atomicamente quando nada a
            segura.
          title: Effect Key
        effect_kind:
          $ref: '#/components/schemas/EffectKind'
          default: delivery
        gateway_id:
          anyOf:
            - pattern: ^[a-z][a-z0-9_]{0,39}$
              type: string
            - type: 'null'
          title: Gateway Id
        intent:
          pattern: ^[a-z][a-z0-9_]{0,39}$
          title: Intent
          type: string
        object:
          anyOf:
            - $ref: '#/components/schemas/ObjectRef'
            - type: 'null'
        purpose:
          pattern: ^[a-z][a-z0-9_]{0,39}$
          title: Purpose
          type: string
        subject:
          anyOf:
            - $ref: '#/components/schemas/Handle'
            - type: 'null'
        task:
          anyOf:
            - pattern: ^[a-z][a-z0-9_]{0,39}$
              type: string
            - type: 'null'
          title: Task
      required:
        - agent
        - intent
        - direction
        - purpose
      title: CheckRequest
      type: object
    CheckResult:
      additionalProperties: false
      description: >-
        A decisão de coordenação. `reasons` são códigos (a especificação de
        coordenação, 4); `holder` é para quem transferir com `handoff_to`.
        `contact_token` vem só com um contato de saída permitido de uma
        finalidade que precisa de um.
      properties:
        channel:
          anyOf:
            - $ref: '#/components/schemas/ChannelState'
            - type: 'null'
        commitments_active:
          items:
            $ref: '#/components/schemas/CommitmentRef'
          title: Commitments Active
          type: array
        contact_budget:
          additionalProperties:
            $ref: '#/components/schemas/ContactBudget'
          title: Contact Budget
          type: object
        contact_token:
          anyOf:
            - maxLength: 1024
              pattern: ^nct1\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]{86}$
              type: string
            - type: 'null'
          title: Contact Token
        decision:
          enum:
            - allow
            - defer
            - deny
            - handoff_to
          title: Decision
          type: string
        decision_id:
          format: uuid
          title: Decision Id
          type: string
        effect:
          anyOf:
            - $ref: '#/components/schemas/EffectStatus'
            - type: 'null'
        holder:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Holder
        locks:
          items:
            $ref: '#/components/schemas/Lock'
          title: Locks
          type: array
        owner:
          anyOf:
            - $ref: '#/components/schemas/Owner'
            - type: 'null'
        promises_open:
          items:
            $ref: '#/components/schemas/PromiseRef'
          title: Promises Open
          type: array
        reasons:
          items:
            maxLength: 256
            minLength: 1
            type: string
          title: Reasons
          type: array
        suppressions:
          items:
            pattern: ^[a-z][a-z0-9_]{0,39}$
            type: string
          title: Suppressions
          type: array
        valid_for_s:
          minimum: 0
          title: Valid For S
          type: integer
      required:
        - decision
        - decision_id
        - valid_for_s
      title: CheckResult
      type: object
    Problem:
      additionalProperties: false
      description: >-
        Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de
        erros versionado.
      properties:
        code:
          title: Code
          type: string
        detail:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Detail
        request_id:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          title: Request Id
        status:
          title: Status
          type: integer
        title:
          title: Title
          type: string
        type:
          default: about:blank
          title: Type
          type: string
      required:
        - title
        - status
        - code
      title: Problem
      type: object
    EffectKind:
      enum:
        - delivery
        - document
        - notice
        - filing
        - paid_call
        - external_action
      title: EffectKind
      type: string
    ObjectRef:
      additionalProperties: false
      description: Um objeto de negócio num sistema de registro.
      properties:
        id:
          maxLength: 512
          minLength: 1
          title: Id
          type: string
          description: O id nesse sistema.
        namespace:
          maxLength: 256
          minLength: 1
          title: Namespace
          type: string
          description: O sistema onde ele vive, como `erp`.
        type:
          maxLength: 256
          minLength: 1
          title: Type
          type: string
          description: Tipo do objeto, como `invoice`, `order` ou `ticket`.
      required:
        - type
        - namespace
        - id
      title: ObjectRef
      type: object
    Handle:
      additionalProperties: false
      description: >-
        Um identificador de um sujeito num canal ou sistema: um telefone, um
        e-mail, um id do CRM.
      properties:
        scope:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          description: >-
            Espaço de nomes dos identificadores com escopo: a conta do WhatsApp
            Business para `wa_bsuid`, o sistema para `system_id`, o país para
            `gov_id_hmac`.
          title: Scope
        subject_kind:
          anyOf:
            - $ref: '#/components/schemas/SubjectKind'
            - type: 'null'
          description: >-
            O padrão é `person`, exceto nos tipos de handle que só identificam
            organizações.
        type:
          $ref: '#/components/schemas/HandleType'
        value:
          maxLength: 320
          minLength: 1
          title: Value
          type: string
          description: >-
            O identificador. Normalizado no servidor: E.164 para telefone,
            minúsculas para e-mail.
      required:
        - type
        - value
      title: Handle
      type: object
    ChannelState:
      additionalProperties: false
      properties:
        free_form_until:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Free Form Until
        quiet_until:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Quiet Until
        template_required:
          default: false
          title: Template Required
          type: boolean
      title: ChannelState
      type: object
    CommitmentRef:
      additionalProperties: false
      properties:
        id:
          maxLength: 512
          minLength: 1
          title: Id
          type: string
        type:
          pattern: ^[a-z][a-z0-9_]{0,39}$
          title: Type
          type: string
        valid_until:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Valid Until
      required:
        - id
        - type
      title: CommitmentRef
      type: object
    ContactBudget:
      additionalProperties: false
      properties:
        next_allowed_at:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Next Allowed At
        remaining:
          title: Remaining
          type: integer
      required:
        - remaining
      title: ContactBudget
      type: object
    EffectStatus:
      additionalProperties: false
      description: >-
        `none` quer dizer que nada segurava a chave e esta pergunta a reservou:
        quem chama age e depois declara.
      properties:
        attempt:
          anyOf:
            - type: integer
            - type: 'null'
          title: Attempt
        state:
          enum:
            - none
            - in_flight
            - done
            - unknown_outcome
          title: State
          type: string
      required:
        - state
      title: EffectStatus
      type: object
    Lock:
      additionalProperties: false
      properties:
        holder:
          maxLength: 256
          minLength: 1
          title: Holder
          type: string
        kind:
          maxLength: 256
          minLength: 1
          title: Kind
          type: string
        task:
          anyOf:
            - maxLength: 256
              minLength: 1
              type: string
            - type: 'null'
          title: Task
        until:
          format: date-time
          title: Until
          type: string
      required:
        - kind
        - holder
        - until
      title: Lock
      type: object
    Owner:
      additionalProperties: false
      description: >-
        Quem detém o cliente ou o objeto agora: a reivindicação válida mais
        restritiva, de onde veio e até quando. `epoch` protege uma liberação.
      properties:
        epoch:
          title: Epoch
          type: integer
        holder:
          maxLength: 256
          minLength: 1
          title: Holder
          type: string
        kind:
          $ref: '#/components/schemas/ClaimKind'
        level:
          pattern: ^[a-z][a-z0-9_]{0,39}$
          title: Level
          type: string
        since:
          format: date-time
          title: Since
          type: string
        source:
          maxLength: 256
          minLength: 1
          title: Source
          type: string
        valid_until:
          format: date-time
          title: Valid Until
          type: string
        via:
          $ref: '#/components/schemas/ClaimVia'
      required:
        - holder
        - kind
        - level
        - source
        - via
        - since
        - valid_until
        - epoch
      title: Owner
      type: object
    PromiseRef:
      additionalProperties: false
      properties:
        due:
          anyOf:
            - format: date-time
              type: string
            - type: 'null'
          title: Due
        id:
          maxLength: 512
          minLength: 1
          title: Id
          type: string
        owner:
          maxLength: 256
          minLength: 1
          title: Owner
          type: string
      required:
        - id
        - owner
      title: PromiseRef
      type: object
    SubjectKind:
      enum:
        - person
        - account
        - partner
      title: SubjectKind
      type: string
      description: >-
        Uma pessoa, uma organização cliente (`account`) ou uma organização que
        participa sem ser cliente (`partner`).
    HandleType:
      enum:
        - phone_e164
        - wa_id
        - wa_jid
        - wa_lid
        - wa_bsuid
        - email
        - gov_id_hmac
        - app_user_id
        - system_id
        - org_registry_hmac
        - email_domain
        - anon_id
      title: HandleType
      type: string
      description: >-
        O tipo de identificador. O valor é classificado pelo formato, nunca pelo
        campo de onde veio.
    ClaimKind:
      enum:
        - owner
        - case
        - task_lock
      title: ClaimKind
      type: string
    ClaimVia:
      description: >-
        Os três caminhos de entrada: uma declaração pela API, uma observação
        mapeada de um webhook, uma observação que o worker da empresa leu e
        enviou.
      enum:
        - declaration
        - mapping
        - worker
      title: ClaimVia
      type: string
  securitySchemes:
    sourceKey:
      type: http
      scheme: bearer
      description: nia_sk_...

````