> ## Documentation Index > Fetch the complete documentation index at: https://docs.usecorvex.com.br/llms.txt > Use this file to discover all available pages before exploring further. # Criar checkout externo > Abre um checkout Corvex a partir do carrinho do seu front (Lovable, Framer, HTML, etc.). **Autenticação:** header `x-api-key` copiado em **Configuração** da loja. Não use `Authorization: Bearer cvx_live_...` nem `X-Store-Id`. **Preços:** inteiros em centavos (R$ 99,90 → `9990`). **`cart.token`:** identificador único do carrinho no seu app (recomendado: `crypto.randomUUID()`). **`checkoutId`** só vem na resposta. Alias equivalente: `POST /api/stores/external/checkout`. ## OpenAPI ````yaml /openapi.json post /stores/external/checkout openapi: 3.0.3 info: title: Corvex API version: 1.0.0 description: >- API pública da Corvex para gerenciar catálogo, pedidos, checkout marketing, webhooks, clientes e leads. Autenticação exclusiva por API Key (`Authorization: Bearer cvx_live_...`). servers: - url: https://apiv3.usecorvex.com.br description: Produção - url: http://localhost:3333 description: Desenvolvimento local security: - bearerAuth: [] tags: - name: Checkout externo description: >- Criar link de pagamento a partir de um carrinho no seu site. Autenticação com `x-api-key` do painel (não é a API v1 `cvx_live_...`). - name: Produtos description: >- Catálogo da loja. Variantes aparecem só na consulta por id, em modo leitura. - name: Coleções description: Categorias da loja. Use para agrupar produtos na vitrine. - name: Kits description: Pacotes de produtos vendidos juntos. - name: Pedidos description: Pedidos da loja. Criar pedido continua no checkout, não nesta API. - name: Rastreio description: Envios e códigos de rastreio. - name: Carrinhos abandonados description: Checkouts iniciados e não concluídos. - name: Clientes description: Compradores agrupados por documento. - name: Leads description: Contatos capturados na loja virtual. - name: Order bumps description: Ofertas extras no checkout. - name: Brindes description: Brindes liberados por regras de carrinho. - name: Upsell one-click description: Oferta pós-compra com um clique. - name: Cupons description: 'Cupons de desconto. Não há exclusão: altere o status.' - name: Faixas de desconto description: Desconto progressivo por valor ou quantidade. - name: Desconto por pagamento description: Percentual por PIX, cartão ou boleto. Um desconto por método. - name: Webhooks description: >- URLs chamadas quando eventos da loja acontecem. O secret nunca é devolvido. - name: Automações description: >- Fluxos, templates de mensagem e metatags. Automações novas nascem desativadas (`active: false`). paths: /stores/external/checkout: post: tags: - Checkout externo summary: Criar checkout externo description: >- Abre um checkout Corvex a partir do carrinho do seu front (Lovable, Framer, HTML, etc.). **Autenticação:** header `x-api-key` copiado em **Configuração** da loja. Não use `Authorization: Bearer cvx_live_...` nem `X-Store-Id`. **Preços:** inteiros em centavos (R$ 99,90 → `9990`). **`cart.token`:** identificador único do carrinho no seu app (recomendado: `crypto.randomUUID()`). **`checkoutId`** só vem na resposta. Alias equivalente: `POST /api/stores/external/checkout`. operationId: createExternalCheckout requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateExternalCheckoutRequest' example: cart: token: uuid-unico-deste-carrinho currency: BRL items: - title: Nome do produto quantity: 1 unitPrice: 9990 image: https://cdn.exemplo.com/produto.jpg subtotalPrice: null totalPrice: null totalDiscount: 0 requiresShipping: true discounts: [] metadata: null customer: name: null email: null phone: null document: null redirect: successUrl: null cancelUrl: null metadata: null responses: '201': description: Checkout criado. Redirecione o comprador para `checkoutUrl`. content: application/json: schema: $ref: '#/components/schemas/CreateExternalCheckoutResponse' example: success: true checkoutId: a1b2c3d4-e5f6-7890-abcd-ef1234567890 checkoutUrl: >- https://minhaloja.com.br/pay/a1b2c3d4-e5f6-7890-abcd-ef1234567890 storeId: 11111111-1111-4111-8111-111111111111 cartToken: uuid-unico-deste-carrinho '400': $ref: '#/components/responses/ExternalCheckoutInvalidPayload' '401': $ref: '#/components/responses/ExternalCheckoutUnauthorized' '403': $ref: '#/components/responses/ExternalCheckoutForbidden' '404': $ref: '#/components/responses/ExternalCheckoutNotFound' '500': $ref: '#/components/responses/ExternalCheckoutInternalError' security: - checkoutApiKey: [] components: schemas: CreateExternalCheckoutRequest: type: object required: - cart properties: cart: type: object required: - items properties: token: type: string maxLength: 200 description: Único por carrinho lógico no seu app. currency: type: string enum: - BRL default: BRL items: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/ExternalCheckoutItem' subtotalPrice: type: integer minimum: 0 nullable: true totalPrice: type: integer minimum: 0 nullable: true totalDiscount: type: integer minimum: 0 default: 0 requiresShipping: type: boolean default: true discounts: type: array maxItems: 20 items: type: object required: - title - type - value - amount properties: title: type: string maxLength: 200 type: type: string enum: - percentage - fixed - shipping value: type: number minimum: 0 amount: type: integer minimum: 0 metadata: type: object nullable: true additionalProperties: true customer: type: object nullable: true properties: name: type: string maxLength: 200 nullable: true email: type: string format: email maxLength: 320 nullable: true phone: type: string maxLength: 30 nullable: true document: type: string maxLength: 20 nullable: true redirect: type: object nullable: true properties: successUrl: type: string format: uri maxLength: 2000 nullable: true cancelUrl: type: string format: uri maxLength: 2000 nullable: true metadata: type: object nullable: true additionalProperties: true CreateExternalCheckoutResponse: type: object properties: success: type: boolean example: true checkoutId: type: string format: uuid checkoutUrl: type: string format: uri storeId: type: string format: uuid cartToken: type: string ExternalCheckoutItem: type: object required: - title - quantity - unitPrice - image properties: title: type: string minLength: 1 maxLength: 500 description: type: string maxLength: 5000 quantity: type: integer minimum: 1 maximum: 999 unitPrice: type: integer minimum: 0 description: Centavos. originalUnitPrice: type: integer minimum: 0 discountedUnitPrice: type: integer minimum: 0 linePrice: type: integer minimum: 0 originalLinePrice: type: integer minimum: 0 totalDiscount: type: integer minimum: 0 image: type: string format: uri maxLength: 2000 description: URL absoluta http/https. externalProductId: type: string maxLength: 100 externalVariantId: type: string maxLength: 100 sku: type: string maxLength: 100 url: type: string maxLength: 2000 vendor: type: string maxLength: 200 productType: type: string maxLength: 200 requiresShipping: type: boolean default: true options: type: array maxItems: 20 items: type: object required: - name - value properties: name: type: string maxLength: 100 value: type: string maxLength: 200 metadata: type: object additionalProperties: true responses: ExternalCheckoutInvalidPayload: description: Payload inválido (`INVALID_PAYLOAD`). content: application/json: example: success: false error: code: INVALID_PAYLOAD message: Payload inválido details: {} ExternalCheckoutUnauthorized: description: '`MISSING_API_KEY` ou `INVALID_API_KEY`.' content: application/json: example: success: false error: code: MISSING_API_KEY message: Header x-api-key é obrigatório ExternalCheckoutForbidden: description: Loja inativa (`STORE_INACTIVE`). content: application/json: example: success: false error: code: STORE_INACTIVE message: Loja está inativa ExternalCheckoutNotFound: description: Loja não encontrada (`STORE_NOT_FOUND`). content: application/json: example: success: false error: code: STORE_NOT_FOUND message: Loja não encontrada ExternalCheckoutInternalError: description: Erro interno (`INTERNAL_ERROR`). content: application/json: example: success: false error: code: INTERNAL_ERROR message: Erro interno ao processar checkout securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key no formato `cvx_live_...`, criada no painel Corvex. Não use JWT de sessão nem `x-api-key`. checkoutApiKey: type: apiKey in: header name: x-api-key description: >- Chave de checkout copiada em Configuração da loja no painel. Não é `cvx_live_...`. ````