openapi: 3.0.0
paths:
  /partners/accounts:
    get:
      description: >-
        Primeiro pedido de toda integração. Devolve as contas do time da chave;
        o `id` de cada uma é o que vai em `contaInstagram` ao criar automações.


        **Limite:** 60 pedidos por minuto por chave.
      operationId: Partners_listarContas
      parameters: []
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ContaResposta'
        '401':
          description: Chave ausente, inválida ou revogada. Confira o header `X-API-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '429':
          description: >-
            Passou de 60 pedidos no minuto. Espere alguns segundos e tente de
            novo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
      security:
        - chave: []
      summary: Listar as contas Instagram da chave
      tags:
        - Contas e posts
      x-limite-por-minuto: 60
  /partners/accounts/{instagramId}/posts:
    get:
      description: >-
        Para mirar a automação num post que já existe: use o `id` do post em
        `posts: ["<id>"]`.


        **Limite:** 30 pedidos por minuto por chave.
      operationId: Partners_listarPosts
      parameters:
        - name: instagramId
          required: true
          in: path
          description: O `id` da conta (de `GET /partners/accounts`).
          schema:
            example: '17841405503524573'
            type: string
        - name: limite
          required: false
          in: query
          description: Quantos posts (1 a 50).
          schema:
            example: 25
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PostResposta'
        '401':
          description: Chave ausente, inválida ou revogada. Confira o header `X-API-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '403':
          description: Conta desconectada ou com a conexão expirada — reconecte no painel.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '404':
          description: A conta não existe ou não é do time da chave.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '429':
          description: >-
            Passou de 30 pedidos no minuto. Espere alguns segundos e tente de
            novo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
      security:
        - chave: []
      summary: Listar os posts recentes de uma conta
      tags:
        - Contas e posts
      x-limite-por-minuto: 30
  /partners/automations:
    get:
      description: >-
        Da criada mais recente para a mais antiga (ordem estável). O total vem
        no header `X-Total-Count` — pagine enquanto `offset + limite <
        X-Total-Count`.


        **Limite:** 60 pedidos por minuto por chave.
      operationId: Partners_listarAutomacoes
      parameters:
        - name: limite
          required: false
          in: query
          description: 1 a 100 (padrão 100).
          schema:
            example: 100
            type: string
        - name: offset
          required: false
          in: query
          description: Quantos itens pular (padrão 0).
          schema:
            example: 0
            type: string
        - name: conta
          required: false
          in: query
          description: Só as automações desta conta Instagram (o `id`).
          schema:
            type: string
      responses:
        '200':
          headers:
            X-Total-Count:
              description: Total de automações do filtro.
              schema:
                type: integer
          description: ''
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AutomacaoResumoResposta'
        '401':
          description: Chave ausente, inválida ou revogada. Confira o header `X-API-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '429':
          description: >-
            Passou de 60 pedidos no minuto. Espere alguns segundos e tente de
            novo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
      security:
        - chave: []
      summary: Listar as automações
      tags:
        - Automações
      x-limite-por-minuto: 60
    post:
      description: >-
        Alguém comenta no post → recebe uma resposta pública → recebe a 1ª
        mensagem no direct. Você manda a "receita" (o que dispara e o que
        enviar) e a plataforma monta o fluxo. A API não envia mensagem: quem
        dispara é o comentário real.


        Para cards (carrossel de produtos), basta o link de afiliado: a foto e o
        nome saem da própria página do link, e a resposta mostra o que foi
        extraído em `carrosseis`.


        **Limite:** 30 pedidos por minuto por chave.
      operationId: Partners_criarAutomacao
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CriarAutomacaoDto'
            examples:
              comentaQuero:
                summary: Comenta QUERO no próximo post (o clássico)
                value:
                  nome: Comenta QUERO — Planner
                  contaInstagram: '17841405503524573'
                  palavras:
                    - quero
                    - eu quero
                  posts: proximo
                  respostaPublica:
                    - Te enviei no direct! 😉
                    - Enviado, confere lá! 😊
                  mensagens:
                    - texto: >-
                        Oi! Vi seu comentário 🤗 Toque abaixo para receber o
                        link:
                      botoes:
                        - rotulo: Quero o link
                          acao: continuar
                    - texto: 'Aqui está: https://loja.exemplo.com/planner ✨'
              carrossel:
                summary: Carrossel de produtos (achadinhos) — só nome e link
                value:
                  nome: Achadinhos de beleza — comenta QUERO
                  contaInstagram: '17841405503524573'
                  palavras:
                    - quero
                  posts: todos
                  respostaPublica:
                    - Te mandei os links no direct! 😍
                  mensagens:
                    - texto: 'Separei os achadinhos pra você 💖 Toque abaixo:'
                      botoes:
                        - rotulo: Ver os produtos
                          acao: continuar
                    - cards:
                        - nome: Pó translúcido Bella
                          link: https://s.shopee.com.br/4ftndxVAcy
                        - nome: Base matte X
                          link: https://s.shopee.com.br/outroLink
                        - link: https://s.shopee.com.br/maisUm
              postsEspecificos:
                summary: Só em posts escolhidos, com botão de link no fim
                value:
                  nome: Comenta QUERO — só no post do lançamento
                  contaInstagram: '17841405503524573'
                  palavras:
                    - quero
                  posts:
                    - '18100000001'
                  mensagens:
                    - texto: 'Oba! Toque abaixo para receber o cupom:'
                      botoes:
                        - rotulo: Quero o cupom
                          acao: continuar
                    - texto: 'Seu cupom: LANCA10 🎉'
                      botoes:
                        - rotulo: Ir para a loja
                          acao:
                            link: https://loja.exemplo.com
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomacaoCriadaResposta'
        '400':
          description: Receita inválida — a mensagem diz exatamente o que corrigir.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '401':
          description: Chave ausente, inválida ou revogada. Confira o header `X-API-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '403':
          description: >-
            Teto de automações da chave atingido, ou conta
            desconectada/expirada.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '404':
          description: A conta não existe ou não é do time da chave.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '429':
          description: >-
            Passou de 30 pedidos no minuto. Espere alguns segundos e tente de
            novo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
      security:
        - chave: []
      summary: Criar uma automação "comenta QUERO"
      tags:
        - Automações
      x-limite-por-minuto: 30
  /partners/automations/{id}:
    get:
      description: >-
        Tudo da listagem mais a resposta pública e as mensagens, lidas do fluxo
        gravado, no formato da receita.


        **Limite:** 60 pedidos por minuto por chave.
      operationId: Partners_obterAutomacao
      parameters:
        - name: id
          required: true
          in: path
          description: ID da automação.
          schema:
            type: string
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomacaoDetalheResposta'
        '401':
          description: Chave ausente, inválida ou revogada. Confira o header `X-API-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '404':
          description: A automação não existe ou não é do time da chave.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '429':
          description: >-
            Passou de 60 pedidos no minuto. Espere alguns segundos e tente de
            novo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
      security:
        - chave: []
      summary: Ver uma automação
      tags:
        - Automações
      x-limite-por-minuto: 60
  /partners/automations/{id}/status:
    patch:
      description: >-
        Mande `{ "ativa": true }` para ligar ou `{ "ativa": false }` para
        desligar. Repetir o mesmo pedido não inverte nada (`alterada: false`).
        Religar uma automação com `"proximo"` reinicia a espera pelo próximo
        post.


        **Limite:** 60 pedidos por minuto por chave.
      operationId: Partners_atualizarStatusAutomacao
      parameters:
        - name: id
          required: true
          in: path
          description: ID da automação.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtualizarStatusAutomacaoDto'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusAlteradoResposta'
        '400':
          description: O fluxo não passou na validação para ligar.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '401':
          description: Chave ausente, inválida ou revogada. Confira o header `X-API-Key`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '403':
          description: Plano vencido ou conta sem permissão para ligar.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '404':
          description: A automação não existe ou não é do time da chave.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
        '429':
          description: >-
            Passou de 60 pedidos no minuto. Espere alguns segundos e tente de
            novo.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErroResposta'
      security:
        - chave: []
      summary: Ligar ou desligar uma automação
      tags:
        - Automações
      x-limite-por-minuto: 60
info:
  title: API de parceiros Notifiquei
  description: >-
    API para parceiros criarem e gerenciarem automações "comenta QUERO" nas
    contas Instagram de um time da Notifiquei.


    **Como começar:** o dono do time gera uma chave em
    [app.notifiquei.com.br/api-keys](https://app.notifiquei.com.br/api-keys). Na
    [referência](https://notifiquei.com.br/developers/referencia), clique em
    **Authorize**, cole a chave e use **Try it out** em qualquer rota.


    **A API não envia mensagem.** Ela só cria a configuração; quem dispara o
    envio é o comentário real no Instagram.


    Guia completo, exemplos e erros comuns:
    [notifiquei.com.br/developers](https://notifiquei.com.br/developers).


    ### Novidades

    - **14/10/2026 (v1.2.277)** — Pedir para seguir a conta agora é opcional

    - **13/10/2026 (v1.2.276)** — A especificação OpenAPI agora fica em
    notifiquei.com.br

    - **13/10/2026 (v1.2.275)** — A documentação mudou para
    notifiquei.com.br/developers
  version: v1 · 1.2.277
  contact: {}
tags:
  - name: Contas e posts
    description: Descubra as contas da chave e os posts de cada uma.
  - name: Automações
    description: Crie, consulte, ligue e desligue automações "comenta QUERO".
servers:
  - url: https://api.notifiquei.com.br
    description: Produção
components:
  securitySchemes:
    chave:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Chave do time (começa com `ntq_live_`). Gere em
        app.notifiquei.com.br/api-keys.
  schemas:
    ContaResposta:
      type: object
      properties:
        id:
          type: string
          description: >-
            ID da conta Instagram. É o que vai em `contaInstagram` e
            `instagramId`.
          example: '17841405503524573'
        usuario:
          type: string
          example: minhaloja
        tipo:
          type: string
          example: BUSINESS
          nullable: true
        seguidores:
          type: number
          example: 12400
          nullable: true
        situacao:
          type: string
          enum:
            - ativa
            - conexao_expirada
            - desconectada
          example: ativa
        podeCriarAutomacao:
          type: boolean
          description: >-
            Se `false`, o dono precisa reconectar a conta no painel antes de
            criar automações.
          example: true
      required:
        - id
        - usuario
        - situacao
        - podeCriarAutomacao
    ErroResposta:
      type: object
      properties:
        message:
          description: >-
            O que deu errado, em português. Em erro de validação pode vir uma
            lista.
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: Chave de API inválida
        statusCode:
          type: number
          example: 401
        error:
          type: string
          example: Unauthorized
        timestamp:
          type: string
          example: '2026-10-13T20:00:00.000Z'
        path:
          type: string
          example: /partners/accounts
      required:
        - message
        - statusCode
        - timestamp
        - path
    PostResposta:
      type: object
      properties:
        id:
          type: string
          description: 'ID do post — use em `posts: ["<id>"]`.'
          example: '18100000001'
        legenda:
          type: string
          description: Começo da legenda (até 140 caracteres).
          example: Promoção do planner — comenta QUERO
          nullable: true
        tipo:
          type: string
          example: IMAGE
        link:
          type: string
          example: https://instagram.com/p/xxxx
        publicadoEm:
          type: string
          example: '2026-08-01T10:00:00Z'
      required:
        - id
        - tipo
        - link
        - publicadoEm
    ContaCurtaResposta:
      type: object
      properties:
        id:
          type: string
          example: '17841405503524573'
        usuario:
          type: string
          example: minhaloja
      required:
        - id
        - usuario
    AlvoResposta:
      type: object
      properties:
        posts:
          description: >-
            `"todos"`, `"proximo"` (enquanto espera o próximo post) ou a lista
            de IDs de post.
          oneOf:
            - type: string
              enum:
                - todos
                - proximo
            - type: array
              items:
                type: string
          example:
            - '18100000001'
        aguardandoProximoPost:
          type: boolean
          example: false
        aguardandoDesde:
          type: string
          description: Desde quando espera o próximo post (só aparece enquanto espera).
          example: '2026-08-21T13:11:08.000Z'
        postVinculadoEm:
          type: string
          description: Quando um `"proximo"` se prendeu ao post publicado.
          example: '2026-08-03T20:12:07.000Z'
          nullable: true
      required:
        - posts
        - aguardandoProximoPost
    AutomacaoResumoResposta:
      type: object
      properties:
        id:
          type: string
          example: a1b2c3d4-0000-4000-8000-000000000000
        nome:
          type: string
          example: Comenta QUERO — Planner
        ativa:
          type: boolean
          example: true
        conta:
          $ref: '#/components/schemas/ContaCurtaResposta'
        alvo:
          $ref: '#/components/schemas/AlvoResposta'
        palavras:
          description: Palavras que disparam. Vazio = qualquer comentário.
          example:
            - quero
          type: array
          items:
            type: string
        criadaEm:
          type: string
          example: '2026-08-03T20:00:00.000Z'
        atualizadaEm:
          type: string
          example: '2026-08-12T14:30:00.000Z'
      required:
        - id
        - nome
        - ativa
        - conta
        - alvo
        - palavras
        - criadaEm
        - atualizadaEm
    AutomacaoDetalheResposta:
      type: object
      properties:
        id:
          type: string
          example: a1b2c3d4-0000-4000-8000-000000000000
        nome:
          type: string
          example: Comenta QUERO — Planner
        ativa:
          type: boolean
          example: true
        conta:
          $ref: '#/components/schemas/ContaCurtaResposta'
        alvo:
          $ref: '#/components/schemas/AlvoResposta'
        palavras:
          description: Palavras que disparam. Vazio = qualquer comentário.
          example:
            - quero
          type: array
          items:
            type: string
        criadaEm:
          type: string
          example: '2026-08-03T20:00:00.000Z'
        atualizadaEm:
          type: string
          example: '2026-08-12T14:30:00.000Z'
        respostaPublica:
          example:
            - Te enviei no direct! 😉
          type: array
          items:
            type: string
        mensagens:
          type: array
          description: >-
            Mensagens do direct, lidas do fluxo gravado, no mesmo formato da
            receita.
          items:
            type: object
          example:
            - texto: Clique abaixo 👇
              botoes:
                - rotulo: Quero o link
                  acao: continuar
            - texto: 'Aqui está: https://loja.exemplo.com/planner'
        exigirSeguir:
          type: boolean
          example: false
          description: O fluxo cobra "seguir a conta" antes dos links?
      required:
        - id
        - nome
        - ativa
        - conta
        - alvo
        - palavras
        - criadaEm
        - atualizadaEm
        - respostaPublica
        - mensagens
        - exigirSeguir
    BotaoDto:
      type: object
      properties:
        rotulo:
          type: string
          description: Texto do botão (até 20 caracteres, limite da Meta).
          example: Quero o link
        acao:
          description: >-
            `"continuar"` envia a PRÓXIMA mensagem da lista (precisa existir
            uma). `{ "link": "https://..." }` abre um site.
          oneOf:
            - type: string
              enum:
                - continuar
            - type: object
              properties:
                link:
                  type: string
                  example: https://loja.exemplo.com
              required:
                - link
          example: continuar
      required:
        - rotulo
        - acao
    CardDto:
      type: object
      properties:
        nome:
          type: string
          description: Título do card (até 80). Se faltar, sai do título da página do link.
          example: Pó translúcido Bella
        link:
          type: string
          description: Link de afiliado — vira o botão do card.
          example: https://s.shopee.com.br/4ftndxVAcy
        imagem:
          type: string
          description: URL pública da foto. Se faltar, sai da própria página do link.
        descricao:
          type: string
          description: Linha menor abaixo do nome (até 80).
        botao:
          type: string
          description: Texto do botão do card (até 20).
          default: Comprar
      required:
        - link
    MensagemDto:
      type: object
      properties:
        texto:
          type: string
          description: Texto da mensagem. Obrigatório quando a mensagem não é de cards.
          example: 'Oi! Vi seu comentário 🤗 Clique abaixo para receber o link:'
        botoes:
          description: Até 3 botões. Mensagem de cards não leva botões.
          type: array
          items:
            $ref: '#/components/schemas/BotaoDto'
        cards:
          description: >-
            Carrossel de produtos (1 a 10 cards). Uma mensagem tem `texto` OU
            `cards`, nunca os dois.
          type: array
          items:
            $ref: '#/components/schemas/CardDto'
    CriarAutomacaoDto:
      type: object
      properties:
        nome:
          type: string
          description: Nome da automação no painel.
          example: Comenta QUERO — Planner
        contaInstagram:
          type: string
          description: ID da conta Instagram — o `id` de `GET /partners/accounts`.
          example: '17841405503524573'
        palavras:
          description: >-
            Palavras que disparam a automação. Sem este campo, qualquer
            comentário dispara.
          example:
            - quero
            - eu quero
          type: array
          items:
            type: string
        posts:
          description: >-
            Onde a automação vale: `"todos"` (padrão), `"proximo"` (o próximo
            post publicado depois de criar ou religar) ou a lista de IDs de post
            (de `GET /partners/accounts/{id}/posts`). Exatamente `proximo`,
            minúsculo e sem acento.
          oneOf:
            - type: string
              enum:
                - todos
                - proximo
            - type: array
              items:
                type: string
              minItems: 1
          default: todos
          example: todos
        respostaPublica:
          description: >-
            Respostas públicas ao comentário — o sistema sorteia uma. Sem este
            campo, usa um texto padrão.
          example:
            - Te enviei no direct! 😉
            - Enviado, confere lá! 😊
          type: array
          items:
            type: string
        mensagens:
          description: >-
            Sequência de mensagens no direct (1 a 10). Um botão `"continuar"`
            leva à mensagem seguinte.
          type: array
          items:
            $ref: '#/components/schemas/MensagemDto'
        exigirSeguir:
          type: boolean
          description: >-
            Cobrar que a pessoa siga a conta antes de receber os links? Com
            `true`, depois do toque na 1ª mensagem entra o passo "É seguidor?":
            quem não segue recebe um pedido para seguir e um botão "Já estou
            seguindo". Default: `false` (todo mundo recebe).
          default: false
        ativa:
          type: boolean
          description: Criar já ligada?
          default: true
      required:
        - nome
        - contaInstagram
        - mensagens
    CardEcoResposta:
      type: object
      properties:
        nome:
          type: string
          example: Pó translúcido Bella
        imagem:
          type: string
          example: https://down-br.img.susercontent.com/file/sg-11134207-exemplo
        link:
          type: string
          example: https://s.shopee.com.br/4ftndxVAcy
      required:
        - nome
        - imagem
        - link
    CarrosselEcoResposta:
      type: object
      properties:
        mensagem:
          type: number
          description: Número da mensagem (começa em 1).
          example: 1
        cards:
          type: array
          items:
            $ref: '#/components/schemas/CardEcoResposta'
      required:
        - mensagem
        - cards
    AutomacaoCriadaResposta:
      type: object
      properties:
        id:
          type: string
          example: a1b2c3d4-0000-4000-8000-000000000000
        nome:
          type: string
          example: Comenta QUERO — Planner
        ativa:
          type: boolean
          example: true
        conta:
          type: string
          description: Usuário da conta Instagram.
          example: minhaloja
        criadaEm:
          type: string
          example: '2026-08-03T20:00:00.000Z'
        carrosseis:
          description: >-
            Só quando a receita tem cards: o que foi extraído de cada link, para
            você conferir.
          type: array
          items:
            $ref: '#/components/schemas/CarrosselEcoResposta'
      required:
        - id
        - nome
        - ativa
        - conta
        - criadaEm
    AtualizarStatusAutomacaoDto:
      type: object
      properties:
        ativa:
          type: boolean
          description: >-
            `true` liga, `false` desliga. Repetir o mesmo valor não inverte
            nada.
          example: false
      required:
        - ativa
    StatusAlteradoResposta:
      type: object
      properties:
        id:
          type: string
          example: a1b2c3d4-0000-4000-8000-000000000000
        nome:
          type: string
          example: Comenta QUERO — Planner
        ativa:
          type: boolean
          example: false
        alterada:
          type: boolean
          description: >-
            `false` quando a automação já estava nesse estado (pedido repetido
            não inverte nada).
          example: true
        atualizadaEm:
          type: string
          example: '2026-08-12T14:35:00.000Z'
      required:
        - id
        - nome
        - ativa
        - alterada
        - atualizadaEm
externalDocs:
  description: Guia para desenvolvedores
  url: https://notifiquei.com.br/developers