Merge pull request #218 from FacturAPI/FAC-858/feat/assign-customer-to-receipt

javorosas · web-flow · commit 93718e886dfb · 2025-12-23T09:30:58.000-07:00
Add customer assignment to existing receipts in API and docs
diff --git a/website/docs/guides/receipts.mdx b/website/docs/guides/receipts.mdx
@@ -24,6 +24,9 @@ recibos que no fueron facturados.
 Para ver las descripciones de todos los parámetros, consulta la referencia completa del
 método [Crear Recibo](/api/#tag/receipt/operation/createReceipt).
 
+Opcionalmente, puedes asociar un cliente al recibo enviando el campo `customer` (ya sea
+el ID de un cliente existente o el objeto del cliente para crearlo).
+
 <Tabs groupId="codeExamples">
 <TabItem value="js" label="Node.js" default>
 
@@ -111,6 +114,21 @@ curl https://www.facturapi.io/v2/receipts \
 </TabItem>
 </Tabs>
 
+## Asignar un cliente a un recibo existente
+
+Puedes asignar un cliente (o crearlo desde payload) a un recibo existente con el método
+[Asignar cliente a recibo](/api/#tag/receipt/operation/assignReceiptCustomer).
+
+```bash
+curl https://www.facturapi.io/v2/receipts/58e93bd8e86eb318b019743d \
+  -H "Authorization: Bearer sk_test_API_KEY" \
+  -H "Content-Type: application/json" \
+  -X PUT \
+  -d '{
+        "customer": "58e93bd8e86eb318b0197456"
+      }'
+```
+
 ## Portal de Autofactura
 
 Cuando creas un e-receipt, tienes la opción de enviarlo por correo electrónico a tu cliente.
diff --git a/website/i18n/en/docusaurus-plugin-content-docs/current/guides/receipts.mdx b/website/i18n/en/docusaurus-plugin-content-docs/current/guides/receipts.mdx
@@ -25,6 +25,8 @@ receipts that were not invoiced (known as global invoice).
 To see the descriptions of all the parameters, consult the complete reference of the
 method [Create Receipt](/api/#tag/receipt/operation/createReceipt).
 
+Optionally, you can associate a customer to the receipt by sending the `customer` field
+(either the ID of an existing customer or the customer object to create it).
 
 <Tabs groupId="codeExamples">
 <TabItem value="js" label="Node.js" default>
@@ -92,7 +94,7 @@ $receipt = $facturapi->Receipts->create([
 <TabItem value="curl" label="cURL">
 
 ```bash
-curl https://www.facturapi.io/v1/receipts \
+curl https://www.facturapi.io/v2/receipts \
   -H "Authorization: Bearer sk_test_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
@@ -113,6 +115,21 @@ curl https://www.facturapi.io/v1/receipts \
 </TabItem>
 </Tabs>
 
+## Assign a customer to an existing receipt
+
+You can assign a customer (or create it from payload) to an existing receipt with
+[Assign customer to receipt](/api/#tag/receipt/operation/assignReceiptCustomer).
+
+```bash
+curl https://www.facturapi.io/v2/receipts/58e93bd8e86eb318b019743d \
+  -H "Authorization: Bearer sk_test_API_KEY" \
+  -H "Content-Type: application/json" \
+  -X PUT \
+  -d '{
+        "customer": "58e93bd8e86eb318b0197456"
+      }'
+```
+
 ## Self-invoice portal
 
 When you create an e-receipt, you have the option to send it via email to your customer.
@@ -178,7 +195,7 @@ $invoice = $facturapi->Receipts->invoice($receipt->id, [
 <TabItem value="curl" label="cURL">
 
 ```bash
-curl https://www.facturapi.io/v1/receipts/5ebd8e56f5687a013ca0df46/invoice \
+curl https://www.facturapi.io/v2/receipts/5ebd8e56f5687a013ca0df46/invoice \
   -H "Authorization: Bearer sk_test_API_KEY" \
   -H "Content-Type: application/json" \
   -d '{
diff --git a/website/openapi_v2.en.yaml b/website/openapi_v2.en.yaml
@@ -3930,6 +3930,15 @@ paths:
             type: string
           description: |
             Search. Text to search in the description of the receipt's items or the SKU.
+        - in: query
+          name: customer
+          schema:
+            type: string
+            minLength: 24
+            maxLength: 24
+          description: |
+            ID of the customer associated to the receipt.
+          example: "58e93bd8e86eb318b0197456"
         - in: query
           name: payment_form
           schema:
@@ -4035,6 +4044,133 @@ paths:
           $ref: "#/components/responses/Unauthenticated"
         "500":
           $ref: "#/components/responses/UnexpectedError"
+    put:
+      operationId: assignReceiptCustomer
+      tags:
+        - receipt
+      summary: Assign customer to receipt
+      description: |
+        Assign an existing customer (by ID) to a receipt, or create a new one by sending the customer object.
+
+        If the receipt has a registered transaction, the transaction's `counterparty` will also be updated.
+      x-codeSamples:
+        - lang: Bash
+          label: cURL
+          source: |
+            curl https://www.facturapi.io/v2/receipts/58e93bd8e86eb318b019743d \
+              -H "Authorization: Bearer sk_test_API_KEY" \
+              -H "Content-Type: application/json" \
+              -X PUT \
+              -d '{
+                    "customer": "58e93bd8e86eb318b0197456"
+                  }'
+        - lang: JavaScript
+          label: Node.js
+          source: |
+            import Facturapi from 'facturapi'
+            const facturapi = new Facturapi('sk_test_API_KEY');
+
+            // Assign an existing customer by ID
+            const receipt = await facturapi.receipts.assignCustomer(
+              '58e93bd8e86eb318b019743d',
+              { customer: '58e93bd8e86eb318b0197456' }
+            );
+
+            // Or create the customer from payload and assign it to the receipt
+            const receiptWithNewCustomer = await facturapi.receipts.assignCustomer(
+              '58e93bd8e86eb318b019743d',
+              {
+                customer: {
+                  legal_name: 'Dunder Mifflin',
+                  tax_id: 'XAXX010101000',
+                  tax_system: '616',
+                  email: 'billing@dundermifflin.com',
+                  address: { zip: '01234', country: 'MEX' }
+                }
+              }
+            );
+        - lang: csharp
+          label: C#
+          source: |
+            var facturapi = new FacturapiClient("sk_test_API_KEY");
+
+            // Assign an existing customer by ID
+            var receipt = await facturapi.Receipt.AssignCustomerAsync(
+              "58e93bd8e86eb318b019743d",
+              new Dictionary<string, object>
+              {
+                ["customer"] = "58e93bd8e86eb318b0197456"
+              }
+            );
+
+            // Or create the customer from payload and assign it to the receipt
+            var receiptWithNewCustomer = await facturapi.Receipt.AssignCustomerAsync(
+              "58e93bd8e86eb318b019743d",
+              new Dictionary<string, object>
+              {
+                ["customer"] = new Dictionary<string, object>
+                {
+                  ["legal_name"] = "Dunder Mifflin",
+                  ["tax_id"] = "XAXX010101000",
+                  ["tax_system"] = "616",
+                  ["email"] = "billing@dundermifflin.com",
+                  ["address"] = new Dictionary<string, object>
+                  {
+                    ["zip"] = "01234",
+                    ["country"] = "MEX"
+                  }
+                }
+              }
+            );
+        - lang: PHP
+          source: |
+            $facturapi = new Facturapi( "sk_test_API_KEY" );
+
+            // Assign an existing customer by ID
+            $receipt = $facturapi->Receipts->assign_customer("58e93bd8e86eb318b019743d", [
+              "customer" => "58e93bd8e86eb318b0197456"
+            ]);
+
+            // Or create the customer from payload and assign it to the receipt
+            $receiptWithNewCustomer = $facturapi->Receipts->assign_customer("58e93bd8e86eb318b019743d", [
+              "customer" => [
+                "legal_name" => "Dunder Mifflin",
+                "tax_id" => "XAXX010101000",
+                "tax_system" => "616",
+                "email" => "billing@dundermifflin.com",
+                "address" => [
+                  "zip" => "01234",
+                  "country" => "MEX"
+                ]
+              ]
+            ]);
+      parameters:
+        - in: path
+          name: receipt_id
+          schema:
+            type: string
+          required: true
+          description: ID of the receipt to update
+      requestBody:
+        $ref: "#/components/requestBodies/ReceiptAssignCustomer"
+      security:
+        - "SecretLiveKey": []
+        - "SecretTestKey": []
+      responses:
+        "200":
+          description: Updated `Receipt` object
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Receipt"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthenticated"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/UnexpectedError"
     delete:
       operationId: cancelReceipt
       tags:
@@ -7728,6 +7864,12 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/ReceiptInput"
+    ReceiptAssignCustomer:
+      required: true
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/ReceiptAssignCustomerInput"
     ReceiptInvoice:
       required: true
       content:
@@ -11863,6 +12005,10 @@ components:
               type: string
               example: 614496b471d422de4b6cfcc4
               description: ID of the associated invoice, if invoiced.
+            customer:
+              type: string
+              example: 58e93bd8e86eb318b0197456
+              description: ID of the customer associated to the receipt, if assigned.
             key:
               type: string
               example: r9YqYarL
@@ -11892,6 +12038,15 @@ components:
             - items
             - payment_form
           properties:
+            customer:
+              description: |
+                Customer associated to the receipt. You can send the ID of an existing customer or a customer object to create it.
+              oneOf:
+                - type: string
+                  minLength: 24
+                  maxLength: 24
+                  example: 58e93bd8e86eb318b0197456
+                - $ref: "#/components/schemas/CustomerCreateInput"
             items:
               type: array
               maxItems: 5000
@@ -11947,6 +12102,20 @@ components:
           type: string
           description: |
             Optional identifier that you can use to relate this receipt to your records and later search by this number. Facturapi does not validate that this field is unique.
+    ReceiptAssignCustomerInput:
+      type: object
+      required:
+        - customer
+      properties:
+        customer:
+          description: |
+            Customer to assign to the receipt. You can send the ID of an existing customer or a customer object to create it.
+          oneOf:
+            - type: string
+              minLength: 24
+              maxLength: 24
+              example: 58e93bd8e86eb318b0197456
+            - $ref: "#/components/schemas/CustomerCreateInput"
     ReceiptSearchResult:
       allOf:
         - $ref: "#/components/schemas/SearchResult"
diff --git a/website/openapi_v2.yaml b/website/openapi_v2.yaml
